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About This Book 


This book, A/X User Interface Programming Concepts for RISC System/6000, describes 
how to customize the behavior and appearance of the AlXwindows Desktop and Window 
Manager, how to use the AlXwindows toolkit, how to use X-Windows subroutines and 
libraries, how to use the Curses Subroutine Library, and how to design interactive user 
interfaces. It is the programmer’s main source book for learning about user interfaces from 
a programming perspective. 


Who Should Use This Book 


This book is intended for users with programming experience interested in customizing their 
personal AlXwindows environment as well as for experienced C programmers who are 
designing user interfaces for user communities. 


How This Book is Organized 
This book contains six chapters: 


Chapter 1. AlXwindows Desktop, provides information necessary to customize the 
behavior and appearance of the AlXwindows Desktop. 


Chapter 2. AlXwindows Window Management, provides information necessary to tailor 
the window management environment. 


Chapter 3. AlXwindows Toolkit, describes the contents of the AlXwindows toolkit (objects 
and subroutines) and explains how to use them to design interactive user interfaces. 


Chapter 4. AlXwindows Style Guide, facilitates the design of user interfaces with a 
consistant behavior and appearance. 


Chapter 5. Enhanced X-Windows, provides a conceptual introduction to using Enhanced 
X-Windows subroutines, macros, protocols, extensions, and events. 


Chapter 6. Curses and Extended Curses, provides a conceptual overview of the Curses 
and Extended Curses Subroutine Libraries. 


Highlighting 
The following highlighting conventions are used in this book: 
Bold Identifies commands, keywords, files, directories, and other items whose 
names are predefined by the system. 
Italics rata parameters whose actual names or values are to be supplied by 
the user. 


Monospace ___ Identifies examples of specific data values, examples of text similar to what 


you might see displayed, examples of portions of program code similar to 
what you might write as a programmer, messages from the system, or 
information you should actually type. 


Related Publications 
The following books contain information about or related to programming the user Interface: 


AIX Calls and Subroutines Reference for IBM RISC System/6000, Order Number 
$C23-2198. 
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e AIX Commands Reference for IBM RISC System/6000, Order Number SC23-2199. 
e AIX Files Reference for IBM RISC System/6000, Order Number SC23-—2200. 
e Task Index and Glossary for IBM RISC System/6000, Order Number SC23—2201. 


e AIX General Concepts and Procedures for IBM RISC System/6000, Order Number 
$C23-2202. 


e AIX General Programming Concepts for IBM RISC System/6000, Order Number 
SC23-2205. 


e AlX Communications Programming Concepts for IBM RISC System/6000, Order Number 
$C23-2206. 


Ordering Additional Copies of This Book 
To order additional copies of this book, use Order Number SC23-2209. 
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Chapter 1. AlXwindows Desktop 


Customizing the AlXwindows Desktop Overview 


The behavior and appearance of the AlXwindows Desktop are not fixed, but are determined 
by rule files and resource definitions that can be edited to suit individual requirements. 


The resource mechanism determines the default appearance of the main components of the 
Desktop, such as: 


e The font used for text | 

e The spacing around text 

e The spacing between icons 

e Background patterns 

e Mouse cursor shapes and mouse button triggers 

e The thickness of the lines between items on menus 
e Pictures for message boxes 

e Text layout in message windows 

e Pictures for directory controls. 


In addition, the resource files specify the mapping between the mouse clicks and presses 
and the labels used by the system (which are called triggers). These can be altered to work 
with mouses that have a different number or layout of buttons. 


Normally, each computer running the desktop has a resource file suited to the particular 
machine on which it is being run. For example, machines with large screens can use larger 
pictures for window controls to improve legibility. 


However, users can provide their own resource files to give any desired appearance, or can 
switch between resource files to provide different working environments for different 
applications. 


A separate set of files, called rule files, determine: 

e Desktop layout 

e Titles for files and directories 

e Pictures for files and directories 

e Actions when a user double—clicks on an icon 

e Actions when one or more icons are dragged onto another icon 

e Actions when one or more icons are dragged into a directory window 
e Appearance of menus, and the action when a menu item is selected. 


The default behavior of the desktop is determined by a system rule file, but this can be 
overridden by additional rule files that are provided by each user. Furthermore, rule files can 
be created that are local to a specific directory. 
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Rule files consist of a number of different components that determine the following aspects 
of the behavior of the desktop: 


Icon appearance and title The picture displayed for a file or group of files, 
and the title displayed below it. 


Icon activation What happens when the user double clicks the 
mouse on the icon. 


Directory appearance What picture is used to create the background 
pattern for the directory window. 


Drop behavior What happens when one or more icons are 
dragged into a directory window, and what 
happens when another icon is dropped onto an 


icon. 

Menu appearance and behavior What happens when a menu item is selected. 

Desktop layout Which files are on the desktop, and what their 
positions are. 

Locked files Which files are permanently locked on the 
desktop. 


User Interface Guidelines 
The default configuration of the desktop has been designed according to certain general 
principles in order to make the desktop more predictable, and therefore easier to learn and 
use. 


Use the following principles when extending or altering the desktop for specific applications: 


Icon Design 
Standard desktop icons are designed within a 64x64 pixel square. Icons should include a 
border of at least one pixel to avoid icons bleeding onto a similarly shaded desktop pattern. 


If shadows are included in icon designs, the shadow should appear to be cast by a light in 
the top left corner of the screen. 


Icons should have the same scale. For example, a filing drawer should not be smaller than 
the folder it is supposed to contain. 


Generic Icons 
The icons should be consistent in appearance. Visual features should be used to convey 
information about the file that the icon represents. The three main categories of icons 
(directories, documents, and programs) should fall into three visibly consistent sets. For 
example, the standard document icons tend to be portrait in aspect ratio, and the directory 
icons landscape. 


All file and document icons should be created in three forms to distinguish between 
read/write, read only, and locked. 


Typical Applications 
The following examples illustrate how the desktop can be configured for some practical 
applications. 


Simulating Familiar Environments 


Users who are already familiar with other desktop—based systems, or who have to share 
their work between the desktop and another desktop system, can configure the desktop to 
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match the appearance and behavior of the other system. Thus they can minimize the errors 
associated with transfer and reduce the amount of relearning needed. 


Associating data files with programs 


By defining appropriate icon rules, each data file can be associated with the most relevant 
program, so that double-clicking on the data file invokes the appropriate program with the 
data file supplied to it. 


Dragging a data file onto a program icon can be used as an alternative method of invoking 
the program. For example, a rule file could be written so that compiler source files were 
edited by dropping the icons which represent them on the Editor icon, and compiled by 
double-clicking on them. 


Identifying Users’ Files 


Icon rules can also be used to change the foreground or background colors of the icons 
representing files according to who own the files. This would enable users to see at a glance 
which files belong to them. 


Background Mail Server 


Trash Icon 


The rule files are flexible enough to allow the creation of applications such as a mail server, 
which posts new mail as an icon on the desktop. The mail server would run as a background 
task, and when mail was received it would run a desktop command language command to 
place the mail file on the desktop. The rule file could specify that double-clicking on a mail 
file would open it in a text editor and delete the original file. 


The Trash Icon is created on the desktop using rule files, with no additional programming. 
The Trash Icon represents a directory, with an appropriate title and picture. It contains a rule 
file that causes any icon either dropped into its directory window or onto the directory icon to 
be moved to the directory. The Trash directory can be cleared by double-click on its icon 
with both mouse buttons. 


The Trash icon would typically be locked onto the desktop by including it in the locked files 
list. 


Automatic Encryption and Decryption 


The drop rules allow directories with special characteristics to be created within the desktop, 
For example, a directory could be created such that all files dragged into it are encrypted. 
The user could decrypt them either by dragging them into another directory window, or by 
double-clicking on their icons. 


Local Rule Files 


Rule files can be local to one user, or even local to a specific directory. User—specific rule 
files can take care of the different computers that different users on an AIX network might be 
using. Each user can then double-click a program file on the network, and run it ona 
computer appropriate to that program. 


Changing Environments 


The desktop is flexible enough that a single user can switch environments at will, thus 
changing both the appearance and behavior of the desktop, by double-clicking on the 
appropriate environment file. 


For example, a user might have two characteristic modes of working, programming and 
documenting. In the first mode, the desktop might display compilers and debuggers, and the 
rule files could specify that double-clicking on source files would run the appropriate 
compiler. In the documenting mode, the desktop might display word—processing and 
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flow—charting programs, and double—clicking on source files would load them into the 
appropriate word processor. 


The default rules accept any file whose name ends in the .xde suffix as an environment file. 
Double—clicking on an environment file with the left mouse button saves the current desktop 
state and changes the desktop to that environment. The default environment when the 
desktop is loaded is xdtinitial.xde. 


How to Create and Edit AlXwindows Desktop Icons 


Using a bitmap editor you can create new and unique icons for your application. 


Prerequisite Conditions 
e The AlXwindows desktop must be running on your terminal. 


e You must have access to a bitmap editor that supports standard AlXwindows bitmaps, 
and have named it bitmap. 


Procedure 
1 


. Open the directory that contains your bitmap files. By default, this directory is named 
/usr/include/X11/bitmaps. 


2. Copy an existing picture file, or the blank blank.px picture file. 
3. Rename the new picture file to the new title, ending in the .px suffix. 


4. Double-click with the left mouse button on the new icon. The desktop runs the bitmap 
editor on the new picture file. 


How to Define the Appearance of AlXwindows Desktop Icons 


Rule files describe how the icons and windows representing files, programs, and directories 
on the desktop appear and behave. The rules files are ASCII files and can be edited with 
any standard text editor. 


Prerequisite Conditions 
e The AlXwindows Desktop must be running on your terminal. 


e The picture file to which you refer in defining the appearance of the icon must exist and 
be located in the path specified by the resources. 


Procedure 
. 1. To edit the rules in these files, drag the icon representing the rule file onto the icon 
representing the editor. By default, the first rule file that the desktop reads is 
xdtinitial.xde in your home directory. If the rule is to apply only to files within a certain 
directory, edit the file named xdtdir.SLANG (where $LANG is the value of your LANG 
environment variable, specifying the language for which you have National Language 


Support) within the appropriate directory. For example, if you use US English, you would 
edit the xdtdir.En_US file. 


2. Create an icon_rules statement in the following format: 
icon_rules { [ FileSpec { FileRules}]...} 


where the icon_rules keyword introduces the rules, and the FileSpec parameter 
specifies the icons to which the rule apply. For example, if the rule is for the icon 
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Examples 
1 


representing the file compress, the FileSpec parameter would be set to compress. The 
FileSpec parameter can also specify groups or classes of icons by including pattern 
matching characters or class specifications. 


. If the rule file already exists, incorporate the new icon rule into the rules the file already 


contains. Insert the icon rule in front of any other icon rules in the file so that it takes 
precedence over them. 


. Create file rules describing the appearance of the icon. For example, to set the title of the 


icon to Squash, use the following statement: 


title =Squash; 


2. To use the compress.px picture file for the icon, use the following statement: 


picture = compress.px 


If this rule is in a directory’s xdtdir.$LANG file, save the rule file and exit the editor, then 
close and reopen the directory window to see the change to the rule file take effect. 


How to Define the Behavior of AlXwindows Desktop File and 
Program Icons 


By editing rule files, you can specify the actions to be performed when the user 
double—clicks a mouse button while the mouse pointer is on an icon. 


Prerequisite Conditions 
e The AlXwindows Desktop must be installed on your system before editing rule files. 


Procedure 


1. 


To edit the rules in these files, drag the icon representing the rule file onto the icon 
representing the editor. By default, the first rule file that the desktop reads when it is run 
is the xdtinitial.xde file in your home directory. If the rule is to apply only to files within a 
certain directory, edit the file named xdtdir.SLANG (where $LANG is the value of your 
LANG environment variable, specifying the language for which you have National 
Language Support) within the appropriate directory. For example, if you use US English, 
you would edit the xdtdir.En_US file. 


. Create a trigger_action statement within the icon_rules statement for the icon, in the 


format: 
trigger_action: TriggerlD { actions { ActionList} } 
The TriggerlD parameter has the following values: 


$1 Double-click on the left mouse button. 

s2 Double-click on the right mouse button. 

$3 Double-click on both mouse buttons. 

s* Double-click on any mouse button for which a rule has not been explicitly 
defined. 

d1 Drag an icon onto this icon using the left mouse button. 

d2 Drag an icon onto this icon using the right mouse button. 

d3 Drag an icon onto this icon using both mouse buttons. 
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Examples 


Ae 


d* Drag an icon onto this icon using any mouse button for which a rule has not 
been explicitly defined. 


The ActionList parameter specifies the commands that are run when the user 
double—clicks with the indicated button on the icon indicated in the FileSpec parameter of 
the icon_rules statement. Each statement in the list of actions is preceded by one of the 
following prefixes: 


background or b In background, by way of the standard AIX shell 
/bin/sh. Standard input, output, and error are the 
/dev/null device. 


terminal_emulation or t Standard AIX shell within the standard terminal 
emulator (normally the aixterm program.) 

internal or d: Statements in the desktop command language. 

logged_background or | Standard AIX shell with output sent to a log file. 


The commands can also include substitutions that refer to components of named files. 


The following rule: 


icon_rules 


af 
*.Z /F 
{ 
trigger_action : sl 
{ 
actions 
{ 
background : uncompress <%P0 >%D0/%E0 
desktop : check %D0/%E0 
} 
} 
} 
} 


indicates that, for all files whose names have the .Z suffix, double-clicking with the left 
mouse button on the file icon will run the AIX uncompress program on the file. The 
desktop then checks the icon for the resulting file. 


~ The rule contains two actions statements, using substitutions to represent the appropriate 


icons and files: 


e background : uncompress <%P0 >%D0/%E0O runs the AIX uncompress 
program, with input from the file represented by the icon, where %P0 represents its 
absolute pathname and output goes to the file in the same directory (as shown by %D0 
), with the same name as the input file, except for the last dot and any subsequent 
characters (as shown by E0 ). 


e desktop : check %D0/%E0 runs the Desktop Command Language chk statement, 
ensuring that the correct icon displays for the output file, which is shown, as in the 
above statement, by D0/%E0. 
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2. The rule: 


icon_rules 


{ 
compress /FX 
{ 
trigger_action : dl 
{ 
once per argument ; 
actions 
{ 
background : %PO0 <%Pl >%P1.Z ; 
desktop : check %P1.2 ; 
i 
} 
} 
} 


indicates that, if the user drags any icons using the left mouse button onto the icon for the 
executable file named compress, each of the files those icons represents is 
compressed. The icon for the file being compressed is then replaced by the icon for the 
compressed file. 


The actions clause works as follows: the path name of the dragged file is substituted for 
%P1, and the first command in the action list runs compress (%P0) on this to create a file 
of the same name with the .Z suffix. The check desktop command then updates the new 
icon. 


How to Define the Behavior of AlIXwindows Desktop Directory 
Icons 


By editing rule files, you can specify the actions to be performed when the user 
double—clicks a mouse button while the mouse pointer is on a directory icon or within a 
directory window. 


Prerequisite Conditions 
e The AlXwindows Desktop must be installed on your system. 


Procedure 
1. To edit the rules in these files, drag the icon representing the rule file onto the icon 

representing the editor. To create rules that apply to all directories, edit the desktop’s 
initial rule file. (By default, this is the xdtinitial.xde file in your home directory). If the rule 
is to apply only to files within a certain directory, edit the file named xdtdir.SLANG (where 
$LANG is the value of your LANG environment variable, specifying the language for 
which you have National Language Support) within the appropriate directory. For 
example, if you use US English, you would edit the xdtdir.En_US file. 


2. Create a directory_rules statement for the icon, in the following format: 
directory rules { drop_in_action... } 
Each drop_in_action is in the format: 
drop_in_action: TriggerID { [ IlconGroup { ActionList}] } 
The TriggerlD parameter has the following values: 
s1 Double-click on the left mouse button. 
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$2 Double-click on the right mouse button. 


$3 Double-click on both mouse buttons. 

s* Double-click on any mouse button for which a rule has not been explicitly 
defined. 

d1 Drag an icon onto this icon using the left mouse button. 


d2 Drag an icon onto this icon using the right mouse button. 
d3 Drag an icon onto this icon using both mouse buttons. 


d* Drag an icon onto this icon using any mouse button for which a rule has not 
been explicitly defined. 


The /conGroup parameter determines how the rule is applied to its group of directories. 


If the conGroup parameter is set to the act_on_all value or the ig=a value (or if the 
parameter is not set), the actions are performed once. The %P* value is expanded to $P1 
%P2 ... before the statement is executed. 


If the /conGroup parameter is set to the once_per_argument value or the ig=i value, the 
actions are run once per icon. For each icon, the desktop substitutes the pathname of the 
file for the sP* value, then executes the statement once. 


The ActionList parameter specifies the commands that are run when the user 
double—clicks with the indicated button on the icon indicated in the FileSpec parameter of 
the icon_rules statement. Each statement in the list of actions is preceded by one of the 
following prefixes: 


background or b In background, by way of the standard AIX shell 
/bin/sh. Standard input, output, and error are the 
/dev/null device. 


terminal_emulation or t Standard AIX shell within the standard terminal 
emulator (normally the aixterm program.) 

internal or d: Statements in the desktop command language. 

logged_background or | Standard AIX shell with output sent to a log file. 


The commands can also include substitutions that refer to components of named files. 
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Examples 


1. The rule: 
directory rules 
{ 
drop_in_action 
{ 
dl 
{ 
once _per argument 
actions 
{ 
desktop : move_into %P0 %Pl 
background : compress %P0/%B1 
desktop : check %P0/%Bl1l 
desktop : check —R %P0/%B1 
} 
} 
} 
} 


moves icons into the directory, then compresses the files and redisplays the icons for the 
compressed files. 


The rule contains the following actions statements: 


desktop : move_into %P0 %P1 uses the desktop command language statement 
move_into to move the file represented by the dropped icon (using the substitution 
%P1 ) into the directory represented by the directory window into which it was dropped 
(using the substitution %P0). 


background : compress %P0/%B1 runs the AIX compress program on the file 
represented by the icon. The statement refers to the file’s absolute pathname and 
filename by the substitution ¢P0/%P1. 


desktop : check %P0/%B1 redraws the icon’s image, if necessary. 


desktop : check —R %P0/%B1 indicates that if the file no longer exists, the icon is 
removed. 


The once_per_argument option, included in the list of files for the drop_in_action 
clause, specifies that the rules should be run with appropriate file substitutions for each 
icon dropped into the directory window. Otherwise the rules would be executed only 
once, even when several icons were dropped in. 
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2. The rule could also be specified for the directory’s icon: 


icon_rules 


{ 
compress /D 
{ 
trigger_action : dl 
{ 
once _per_ argument ; 
actions 
{ 
desktop : mvi %P0 %Pl 
background : compress %P0/%B1l 
desktop : chk %P0/%Bl 
desktop : chk —R %P0/%B1 
} 
} 
} 
} 


How to Create and Edit AlXwindows Desktop Menus 


By adding menu statements to the appropriate rule file you can customize the desktop 


menus to fit your applications. 


Prerequisite Conditions 
e The AlXwindows Desktop must be installed on your system. 


Procedure 


1. Create a menu statement within the appropriate rule file. To create rules that apply to all 


directories, edit the initial rule file. (By default, this is xdtinitial.xde in your home 
directory). If the rule is to apply only to files within a certain directory, edit the file named 
xdtdir.$LANG (where $LANG is the value of your LANG environment variable, 
specifying the language for which you have National Language Support) within the 
appropriate directory. For example, if you use US English, you would edit the 
xdtdir.En_US file. 


The menu statement has the following format: 
menu : MenuName { [ menu_item ] ... [ dividing_line ] ... } 
where MenuName is the name of the new menu. 


. The menu_item entries can include either actions to be performed or the name of a 


secondary menu that appears when the user selects the menu item. 

The menu_item statements for actions have the following format: 
menu_item : /temName { [ ActionList] ... } 

The /temName shows the name of the menu item as it appears on the menu. 


The ActionList parameter specifies the commands that are run when the user 
double—clicks with the indicated button on the icon indicated in the FileSpec parameter of 
the icon_rules statement. Each statement in the list of actions is preceded by one of the 
following prefixes: 
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Examples 


1. 


background or b In background, by way of the standard AIX shell 
/bin/sh. Standard input, output, and error are the 
/dev/null device. 


terminal_emulation or t Standard AIX shell within the standard terminal 
emulator (normally the aixterm program.) 


internal or d: Statements in the desktop command language. 
logged_background or | Standard AIX shell with output sent to a log file. 


The following statement: 
menu_item : Select All {actions{d:select —A}} 


displays the Select A11 item name on the menu. When the user selects this item, the 
desktop runs the desktop command language select statement to mark all icons within 
the current window as selected. 


. To create menu_item statements for secondary menus, use the following format: 


menu_item : /temName { [ pull_off_menu ]... } 
The /temName shows the name of the menu item as it appears on the menu. 


The pull_off_menu shows the menu name of the menu that appears beside the current 
menu when the menu item is selected. 


For example, the following statement: 


menu_item : Miscellaneous 
{pull_off_menu=pop_mainsub_misc_menu} 


displays the Miscellaneous item name on the menu. When the user selects this item, 
the desktop displays the menu named pop_mainsub misc_menu. 


. To create dividing lines, use the following statement: 


dividing line 
for thin dividing lines, or 
thick dividing line 


for thick dividing lines. 


. To create menu_item statements for labels, use the format: 


menu_item : item_name {} 
with nothing between the braces. 


menu : MainXdtMenu 
{ 
menu_item : Desktop Menu {} 
thick_dividing line; 
menu_item : Help {actions{t: 
pg /usr/lpp/xdt/xdesktop.man}} 
menu_item : Open directory... 


{actions {b:% 
%DIRNAME=‘mgti —name gtiopendir’ 
% %if [ "xSDIRNAME” != x ] 
% then 
% ttellxdt display directory $DIRNAME 
% tfi}} 
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menu_item : Close Directories 

{actions{d:close directories }} 
menu_item : File Info... {actions{b:mxdtinfo %P*}} 
dividing line; . 


menu_item : Select All {actions{d:select —A}} 
menu_item : Deselect All {actions{d:select —U}} 
menu_item : Put back {actions{d:put_back %P*}} 
dividing.line; 

menu_item : Save Desktop... {actions{b:% 


$FILENAME=‘mgti —name gtisavedt’ 
% tif [ "xSFILENAME” != x ] 


% then 
% ttellxdt save_environment $%{FILENAME%}.xde 
% fi }} 


menu_item : Applications 
{pull _off _menu=pop mainsub_app_menu} 
menu_item : Miscellaneous 
{pull_off_menu=pop_mainsub_misc_menu} 
dividing _line; 
menu_item : Exit {actions{b:% 
$if myni —center "Close down X.desktop?” —helpMsg 
"Click on Ok to close down X.desktop%#10# or Cancel to continue 
with this session. 
% then 
% % tellxdt die 
% fi }} 
} 


The item_name parameter shows the label as it appears on the menu. For example, the 
following rule file entry contains the following items: 


Label Action 
Desktop Menu None 
A thick dividing line. 
Help Runs the AIX pg program within a terminal window 


showing the xdesktop.man help file. 


Open Directory... Runs a shell script which opens a dialog window on 
the desktop, prompting the user to enter a directory 
name, then opens the indicated directory. 


File Info . Displays information about the files represented by 
the selected icons. 

Select All Marks all icons on the desktop working surface as 
selected. 

Deselect All Marks all icons on the desktop working surface as 
unselected. 

Put Back Puts back the selected icons. 


A thin dividing line. 


Save desktop... Runs a shell script which opens a dialog window 
prompting the user for the name of a file in which it is 
to save the desktop environment, then saves the 
environment into that file. 
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Applications 


Miscellaneous 
Copy Desktop... 


Displays a secondary menu of applications. You can 
customize the list of applications which you want to 
have in this menu by creating an menu named 
pop_mainsub_app_menu within your 
xdtuser.$LANG rule file (where $LANG is the value 
of your LANG environment variable). 


Displays a secondary menu of miscellaneous items. 


Runs a shell script which opens a dialog window 
asking the user to confirm that the desktop is to close. 
if the user confirms the choice, ends the desktop 
program.File and 


How to Configure the AlXwindows Desktop through Resources 


You can configure many aspects of the appearance and functioning of the desktop by editing 
the resource values in the .Xdefaults file in your home directory or in the 
/usr/lib/X11/SLANG/app—defaults/Xdesktop file (where $LANG is the value of your LANG 
environment variable, referring to a language for which you have National Language 
Support). These are plain text files, and can be edited with any ASCII text editor. 


Prerequisite Conditions 


e The AlXwindows Desktop must be installed on your system. 


Procedure 


1. To put the new values into effect, save the file and exit the editor, and then restart the 


desktop. 


2. To change the string with which the desktop resources begin (if, for example, they conflict 
with another application that also begins its resources with the Xdesktop* string), edit the 
value of the Xdesktop*name resource. Since the desktop reads the value of this 
resource first to determine the name under which it looks up the other values, the value 
of the Xdesktop*name resource can affect the names of all desktop resources with the 
single exception of the Xdesktop*name resource. 


Examples 


1. The resource values for the desktop begin with the Xdesktop* string. For example, the 


following resource entry: 


Xdesktop*iconGrid.spacing: 


100 


indicates that the desktop, in tidying the placement of icons, places them on the screen 
so that the center of each icon is100 pixels away from the center of the next icon. 


2. To set the spacing so that the icons are twice as far apart, change the resource entry to: 


Xdesktop*iconGrid.spacing: 


200 


How to Create Messages and Dialogs through AlXwindows 


Desktop Utilities 


Several utilities are included with the AlXwindows Desktop with which you can display 
messages and create dialog windows from within shell scripts and rule file statements. 
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Prerequisite Conditions 
_@ The AlXwindows Desktop must be installed in your system. 


ie The utilities must be installed within directories in your path. 


Procedure 
If each utility is in your path, you can run each of them from within shell scripts or from the 
command by typing the command name and any arguments. You can include them in 
actions statements within rule files in the following format: 


{ actions { background : command [arguments] ... } } 


Examples 
1. To display a one line message in a window on the desktop, use the mfyi command. For 
example, the following statement: 


mfyi —picture mailbox.px You have new mail. 


displays a window on the screen, displaying a mailbox icon from the bitmap file and the 
message "You have new mail”. The user can remove the window by clicking on the 
displayed icon. 


2. To display a simple question in a window on the desktop and prompt the user to cancel or 
_confirm the answer, use the myni command. For example, the following statement: 


myni —picture question.px Delete file xyz? 
opens a dialog window with: 
e The icon contained in the question. px bit map file 
e The question: Delete file xyz? 


If the user clicks on the confirm button, the myni utility returns a code of 0. If the user 
clicks on the cancel button, the myni utility returns a code of 2. 


3. To display a message in a window on the desktop and prompt the user for a response, 
use the mgti command. For example, the following statement: 


mfyi "What is the name of the file?” 


displays a window on the screen, prompting the user to enter the name of a file. The 
mgti command passes the user’s response to standard output. 


4. To send commands in the desktop command language to a desktop, use the tellxdt 
command. For example, the following command: 


tellxdt get_out_icon /bin/xclock 
places the clock’s icon on the desktop. 


You can also use the tellxdt command, with various arguments, to find out information 
about a file or its icon. For example, the following command: 


tellxdt —t testcode.c 
returns the name of the picture file used for the icon for the testcode.c file 


If the desktop command which tellxdt is executing uses a flag which tellxdt also uses, 
place the entire desktop command in quotation marks. 
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How to Change the Fonts Displayed on the AlXwindows 


Desktop 


The desktop determines the font with which it displays text for its icons and windows by 
reading the value of the Xdesktop*font and Xdesktop*fontList resources. 


Prerequisite Tasks or Conditions 
e The AlXwindows Desktop must be available on your system. 


Procedure 


e You must have an ASCIl editor, such as vi. 


A. 


2. 


To change the font for your own use, edit the .Xdefaults file within your home directory 
with any ASCII editor. 


The /usr/ipp/X11/defaults/Xfonts file contains a list of valid fonts names, along with the 
information that AlXwindows uses in displaying them. A sample fonts file contains: 


1 Rom14.500 0 0 9 20 
2 It114.500 0 2 9 20 
3 B1ldi4.500 0 1 9 20 
4 Rom10.500 0 0 8 14 
5 Rom6.500 0 0 4 8 

6 Rom22.500 0 012 30 
7 Rom29.500 0018 40 
8 Erg14.500 0 0 9 20 
9 Rom7.500 0 0 6 9 

10 Rom8.500 0 0 6 11 
11 Roml1.500 007 r5 
12 Roml6.500 007 22 
13) Roml17.500 0011 23 
14 Bld17.500 0111 23 


. To set the font used on the desktop to one of the defined fonts, enter a value from the 


second column of the table. For example, to use a 14.5 point Roman typeface, set the 
values in the .Xdefaults file to: 


Xdefaults*font: Rom14.500 
Xdefaults*fontList: Rom14.500 


4. For the value to take effect, save the file, then exit the desktop and restart it. 


How to Set the Colors and Bitmapped Images for the Desktop 


Procedure 


1. 


2. 


To change these colors, edit the .Xdefaults file within your home directory with any ASCII 
editor. 


The resources that affect the desktop colors and bitmapped images are in the form: 
Xdesktop* item* feature 
The item parameter can have the following values: 


newlcon Icons for new files or directories. 
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desktopicon 


normal 


message. fatal 


message.alert 
message.fyi 
message.greeting 
textButton 


Icon which identifies the Desktop within the 
AlXwindows window manager icon box. 


Text windows. 


Messages that appear when programs end 
unexpectedly. 


Warning messages. 
Informative messages. 
The message that appears when the Desktop begins. 


The button which appears next to the names of text 
files when the Desktop displays files in name mode. 


The feature parameter can have the following values: 


foreground 
background 


pixmap 


Foreground color. 
Background color. 
The bitmap image used for the display. 


The /usr/Ipp/X11/rgb/rgb.txt file contains a listing of valid color names, and the 
information AlXwindows uses in displaying them on the screen. For example, a section of 
an rgb.txt file might contain: 


112 219 147 aquamarine 

112 219 147 Aquamarine 

50 204 153 medium aquamarine 
50 204 153 MediumAquamarine 
00 0 black» 

00 0 Black 

0 0 255 blue 

0 0 255 Blue 

95 159 159 cadet blue 

95 159 159 CadetBlue 

66 66 111 cornflower blue 
66 66 111 CornflowerBlue 
107 35 142 dark slate blue 
107 35 142 DarkSlateBlue 


To set the background color of the icon for a newly created file to cadet blue, for example, 
edit its resource entry in the .Xdefaults file to read: 


-Xdesktop*newIcon.background: cadet blue 


. The /usr/include/X11/bitmaps directory contains bitmap files, some of which are 
suitable for use as desktop pixmaps. Your desktop may use another directory for its 
pixmaps, as indicated in the Xdesktop*picture.directory resource. To indicate that 
warning messages, for example, are to use the warning.px bitmap file, edit its resource 
entry to read: 


Xdesktop*message.alert.pixmap: warning.px 
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4. For the value to take effect, save the file, then exit the desktop and restart it. 


Using AlXwindows Desktop Rule Files 


This chapter describes how to create and edit rule files for the AlXwindows Desktop and 
provides information on rule file location, structure, contents, interpretation, and 
substitutions. 


Rule files specify the appearance and behavior of the icons representing files on the 
desktop. For example, rule files enable you to 


e Associate an icon image with specific files or groups of files 

e Associate mouse actions with specific functions to be performed 

e Define events that occur when one icon is dropped onto another. 

Rule files are text files, and can be edited with an ASCII text editor such as the vi editor. 
Rule files consist of sequences of clauses. Each clause has one of two forms: either 
keyword = value; 

OR 

keyword { body }{ ; ] 


In the second form the final semicolon is optional. The body section is normally a sequence 
of additional clauses, separated by semicolons. 


In general, the layout of rule files is not critical, and spaces or new lines can be inserted to 
improve readability and make the structure of the rules clearer. 


For example, the following rule: 
icon_rules {* /D{picture=dir.px;} * /F{picture=file.px;}} 
is equivalent to: 


icon_rules 


{ 

* /D 
{ 
picture = dir.px; 
} 

* /F 
{ 
picture = file.px; 
} 

} 


Components of Rule Files 
A rule file consists of a number of text components. These romponens can occur any 
number of times in any order: 


Component Description 


Icon rules Describe which bitmap file contains the image of each icon, what 
the icon title should be, and what occurs when a user triggers the 
icon by double-clicking on it, or drags another icon onto it. 


Directory rules Describe what happens when icons are dragged into directory 
windows. 
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Menu rules Define the title and items of a menu and describe what happens 


when any menu item is selected. 


Desktop layout Lists all icons that appear on the desktop and describes their 
positions. The desktop layout is generated automatically. 

Locked files Indicate which files are locked onto the desktop and cannot be put 
back. 


Location of Rule Files 
Rule files have the following precedence: 


Keywords 


1. 


Local rule file: Placed in any directory. They provide rules that apply only to the files in 
that directory. 


The directoryRuleFile resource determines the name of this file. If it is not specified, the 
file’s name is xdtdir.SLANG, where $LANG is the value of the user’s LANG environment 
variable showing a language code for National Language Support. The value usually 
used in the United States is xdtdir.En_US. 


. Environment rule files: Contain rules and a list of files that are on the desktop. By 


convention, the names of these files have the form *.xde. 


Each user has only one active environment rule file at a time. This file is known as the 
current environment. By switching environment rules as they switch environments, users 
can have different rules for different circumstances. For example, a user might work in a 
programming environment and a text editing environment. 


When a user changes environment, the positions of icons currently on the desktop are 
saved in the old environment rule file, and a new set of positions is read from the new 
environment file to create a new desktop. 


User rule file: Contains rules that apply only to an individual user. 


The userRuleFile resource determines the name of this file. If it is not specified, the file’s 
name is .xdtuserinfo. 


System rule file: Applies to all desktops running on a given machine. There is only one 
such file. It should be changed only by the root user. 


The systemRuleFile resource determines the name of this file. If it is not specified, the 
file’s name is /usr/lpp/xdt/Ipp.Sysinfo/$LANG is the value of the user’s LANG 
environment variable showing a language code for National Language Support. 


The icon_rules and directory_rules statements which use Pattern clauses that refer to 
files by their absolute pathnames override other statements which refer to the files by 
relative pathnames, regardless of the priority of the files that contain them. Thus, for 
example, a system rule file which referred to /usr/include/X11/bitmaps/foo.px would 
override, for that file, a local rule file in /usr/include/X11/bitmaps which would refer to 

* px. 


Rules in rule files are introduced by the following keywords. AlXwindow Desktop Rule File 
Keywords describes the keywords in detail. 


Keyword Description 

actions Specifies the commands that the AlXwindows desktop runs when 
an icon or directory window is triggered, or a menu item is selected. 

desktop_layout Describes the files that are on the desktop, together with their 
positions. 
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directory_rules Describes the actions to be performed when specified triggers occur 
within directory windows. 


drop_in_action Defines the effect of dropping one or more icons into a directory 
window. 

icon_rules Describes the behavior and appearance of files when represented 
by icons. 


locked_on_desktop Specifies the icons to be locked on the desktop. 


menu Defines the items on menus and the actions to be carried out when 
a particular item is selected. 

menu_item Specifies an item on a menu and the action to be performed when 
the item is selected. Used only within menu clauses. 

picture Specifies the bitmap file to be used for the icons for the associated 
files. 

pull_off_menu Specifies a menu to pop up beside the current menu when the 

associated menu item is selected. 

title Assigns a title to the specified files. 

trigger_action Specifies the actions to be carried out when the icon is selected 
using the specified trigger. 


Special Characters 
The following characters have special meanings in rule files: 


Name Special Meaning 

% percent Preprocessor command (Escape Sequences) 
{ open brace Group items 

} close brace End group 

; semicolon Separator 

: colon Separator 

= equal sign Separator 

& ampersand Separator. 


When a semicolon is followed by a close brace it can be omitted. 


Preprocessor Commands (s) | 
The percent symbol is considered an escape character in rule files. It allows special phrases 
and instructions to be included in rule files. Each character string preceded by a % character 
is replaced by another character string at a preprocessing stage (the % character was 
chosen to be distinct from escape characters used for this purpose in AIX). 


Sequence Replaced by 


%% % 
B; 
eh { 
%) } 


%: 
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Comments 


%= = 


%I!e The c character. 


Ht nt The ncharacter code, according to C language number conventions. The n 
value cannot be 0. 

%white% Sequences of white space characters (space, tab, or new line) surrounded 
by the % character are removed. 

%I// Used for comments; characters up to the next new line are ignored. 

%/* Used for comments; characters up to the next %*/ string are ignored. 

%*/ Ends comments. 

%$name$ The contents of the named environment variable replace the sequence. (not 
preprocessed). 


W&name& The contents of the named environment variable replace the sequence. The 
value is preprocessed after it is replaced. 


%+file+ The preprocessed contents of the specified file replace the sequence. 


Other characters can be included by preceding them with the 2! escape sequence. 


Comments can be included in a rule file by prefixing them with the // sequence, which 
causes all characters up to the end of the line to be ignored, as follows: 


icon_rules { * { title =Title;} } %// This title is for all icons. 


Long comments can be preceded by the %/* sequence and followed by the $*/ sequence. 
All characters between these two sequences are ignored. 


Control Characters 


You can include a control code or other special character in a rule file using the following 
sequence: 


%# decimal—code # 

%#O octal—code # 

%#0x hexadecimal—code # 

%#OX hexadecimal—code # 

Note that in the above hexadecimal sequences the 0 character, not the letter O, is required. 


For example, the double—quote character, character code 34 (that can also be represented 
as octal 42 and hexadecimal 22) can be written as follows: 


RH34# 
%#O42# 
%WH#OX22# 
YH#OX22# 


Including Files 


Rule files can include other named rule files by specifying the sequence, as follows: 
$+namet+ 


Path names which do not begin with a slash are relative to the following directories, as 
determined by the rule file being processed: 
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Rule File Directory for relative includes 


xdtsysinfo /usr/lpp/xdt/Ipp.sysinfo 
xdtuserinfo $HOME 

environment $HOME 

.Xdtdirinfo The directory which contains the file 


Including Environment Variables 
The contents of an environment variable can be included in a rule file with the following 


sequences: | 
wH&name& for which the characters in the environment variables 
are preprocessed. 
%$name$ for which none of the characters in the environment 


variables are preprocessed. 


Referring to File Names 
Rule files can refer to files in four ways: 


Absolute path name The full name of the file. It begins with a slash and 
contains all the directories leading to the rule file. 


Base name The name of the file within its directory. It is the part of 
the absolute path name following the last slash. 


Directory name The name of the directory holding the file. It is the part 
of the absolute path name preceding the last slash. 


Relative path If the file is in the $HOME directory, its relative path is 
the same as its base name. If the file is ina 
subdirectory of $HOME, the relative path name is the 
path from the working directory to the file. Otherwise it 
is the same as the absolute path name. 


For example, the various names of the /user/fred/work/letter file are: 


Absolute path name /user/fred/work/letter 
Base name letter 
Dir name /user/fred/work 


The relative path name depends on the value of $HOME: 


$HOME Relative path name 
/user fred/work/letter 
/user/fred work/letter 
/user/fred/work letter 

any other /user/fred/work/letter 


There is one exception: The directory name reference for the root directory, /, is /. (slash 
dot) and its base name is / (slash). 


Substitutions 
Rule files use substitutions to refer to file names that correspond to icons that are triggered 
or dropped. 
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The name of a file can be substituted for the title of its icon, and the names of any of the files 
involved can be substituted into commands in actions_of statements within rule files. 


Substitutions are made by placing a substitution sequence in the rule file at the appropriate 
point. A sequence consists of the following: 


e percent sign (%), 
e letter indicating the information to be substituted, and 
e In some cases, a number or an asterisk (*). 


The following letters must be followed by a number or an asterisk: 


Letter Meaning 

B Base name of the file 

Cc Class of the file (as used by the icon_rules keyword), in capital letters. 

D The name of the directory holding the file. 

E Base name (as for B ), with the last dot and any subsequent characters 
removed. 

R If the file is in a directory under $HOME, the path name of the file relative to 


$HOME. If the file is not in a directory under $HOME, the absolute path 
name of the file. In the titles of icons within directory windows, the base 
name of the file. 


P Absolute path narne of the file 


The number or asterisk determines the file or files for which information is to be 
substituted. The permitted cases are as follows: 


e In picture or title statements, the number 0 indicates the file represented by the icon. 


e In actions_of statements within trigger_action statements for static triggers, the number 
0 represents the file represented by the icon on which the user had clicked. 


e In actions_of statements within dynamic trigger trigger_action clauses, or within 
drop_in_action statements: 


e The number 0 indicates the file represented by the icon onto which the user had dropped 
other icons. 


e The numbers 1 through 9 represent the appropriate file in the list of files dropped onto the 


mim tan taam om meld cemdie mn foe 
ican, If the number is larger than the number of files dropped Onio iné icon, a Aun Vaiués iS 
substituted. 


e An asterisk (*) represents the files of each of the icons dropped in turn. The values are 
separated by spaces. For example, if three icons are dropped, men the %P* sequence is 
the same as the %P1 %P2 %P3 sequence. 


For example, the /fred/jim/data.tmp file is substituted as follows: 
Sequence Substitution 


%PO /fred/jim/data.tmp 
%BO data.tmp 

%E0 data 

%DO /fred/jim 
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%RO /fred/jim/data.tmp 
%CO FXWM (for example) 

The following letters are not followed by numbers or asterisks: 
Letter Meaning 


N In picture or title statements, and in actions_of statements within 
trigger_action statements for static triggers, the number 0. In actions_of 
statements within dynamic trigger trigger_action clauses, or within 
drop_in_action statements, the number of files represented by the icons 
which were dropped. 


T In picture or title statements, null. In actions_of statements within 
trigger_action statements for static triggers, the static trigger identifier. In 
actions_of statements within dynamic trigger trigger_action clauses, or 
within drop_in_action statements, the dynamic trigger identifier. 


X The name of the version of the Desktop. 





AlXwindows Desktop Rule File Keywords 


The AlXwindows keywords are used to control actions in AlXwindows Desktop rule files. The 
AlXwindows keywords are: 


actions or ac 
desktop_layout or dt 
directory_rules or dd 
drop_in_action or da 
icon_rules or ic 
locked_on_desktop or If 
menu or me 
menu_item or mi 
picture or pi 

e pull_off_menu or pm 
e title or ti 

e trigger_action or ta 


eee e868 06 @ 


actions or ac Keyword 


Purpose 
Specifies the commands that the AlXwindows desktop runs when an icon or directory 
window is triggered, or a menu item is selected. 

Syntax 
actions { [ Control: Command ; } ... } 

Description 
actions statements can be empty or contain one or more commands separated by 
semicolons. Each command is preceded by a command identifier or letter specifying how 
the command is to be run. 

Parameters 


Control Specifies how the command is to be run: 
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background or b In background, by way of the standard AIX shell 
: /bin/sh. Standard input, output, an error are the 
/dev/null device. 


terminal_emulation or t Standard AIX shell within the standard terminal 
emulator (normally the aixterm program.) 
internal or d: Statements in the desktop command language. 
logged_background or | Standard AIX shell with output sent to a log file. 
Command Specifies the command to be run. If the Control 


parameter is set to the d value, the command is a 
statement in the desktop command language; if the 
Control parameter is set to another value, the 
command is an AIX command. 


Example 
The following actions statement contains three commands. 


actions 
{ 
terminal emulation : vi myfile.1; 
background : troff <myfile.1 >myfile.1.trf; 
internal : chk myfile.1.trf . 


} 


These commands are run in order, with each being carried out after the previous one has 
finished. However, while the desktop is waiting for one command to finish running, it may be 
doing other things, and several action lists can be running at the same time. 


desktop_layout or dt Keyword 


Purpose 
Describes the files that are on the desktop, together with their positions. 
Syntax 
desktop_layout { [ FileName [@Position ] ;]... } 
Description 
The desktop layout is normally generated automatically by the desktop, but could be 
modified by a program to alter the initial appearance and layout of a ee Desktop layout 
lists that do not appear in environment files are ignored. 
Parameters 
_ FileName specifies the name of a file to be included on the desktop. 
Position Specifies, if present, the position of the icon on the desktop, as indicated by 


the following values: 


Gxy The G value followed by two numbers separated by a comma, shows the x 
and y coordinates of the icon in grid units (as determined by the 
xdt*iconGrid.spacing resource). 


Px,y The P value followed by two numbers separated by a comma, shows the x 
and y coordinates of the icon in pixels. 


F Indicates that the icon is to be placed at the first free position of the grid. 


If the Position parameter is omitted, the icon is placed at the first free position of the grid. 
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Example 


The following example shows the positions of the icons representing several files and 
directories on a desktop: 


desktop_layout 


/ @ G 0 0; 
/usr/bin @ G 1, 0 ; 
/fred @ F ; 
/fred/main @ G 4, 73 
/bin @ P 211, 874 ; 
/fred/data 
} 
The positions specified in the example are described below: 
File or Directory Position 
/ Upper left corner of the grid 
/usr/bin To the right of the icon for the root directory, 
/tred At the first free position of the grid (to the right of the icon 


for /usr/bin) 


/tred/main On the grid, four positions to the right and seven rows 
down from the upper left corner of the directory window. 


/bin At a position 211 pixels to the right and 874 pixels down 
from the upper left corner of the directory window. 


/fred/data At the first free position on the desktop. 


directory_rules or dd Keyword 


Purpose 


Syntax 


Description 


Specifies the actions to be performed when specified triggers occur within directory 
windows. 


directory_rules { [drop_in_action) ... } 


A directory_rules clause within the rule file for a directory refers to that directory, as if.it had 
been specified in an appropriate file clause in the parent directory’s rule file. The entries ina 
directory_rules clause in any other rule file apply to all directories, as if they had been 
specified in an icon_rules clause with the * pattern and the D class. 


For example, the directory_rules clause: 
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directory rules { | 
drop_in_action : dl { 
actions { 
desktop : move_into %PQ %P* 
} 


drop_in action : d2 { 
actions { 
desktop : copy_into %P0 %P* 


} 
} 
drop_in_action : d3 { 
actions { 
desktop : link_into %P0 %P* 
} 
} 


} 
has these effects: 
e lf the user drags icons into the directory window using the left mouse button, the files 
which the icons represent are moved into the directory. (The substitution $P0 represents 


the absolute pathname of the directory; the substitution P* represents the absolute 
pathnames of each of the icons which are dragged into the directory window.) 


e If the user drags icons into the directory window using the right mouse button, the files 
which the icons represent are copied into the directory. 


e lf the user drags icons into the directory window using both mouse buttons, the files which 
the icons represent are copied into the directory. 


drop_in_action or da Keyword 


Purpose 
Defines the effect of dropping one or more icons into a directory window. 
Syntax 
drop_in_action : Trigger { [actions] ... [IconGroup)] ... } 
Description 
Parameters 

Trigger Specifies the trigger action for which the actions are performed. 

Actions Specifies the actions to be performed. 

IconGroup Specifies how many times the action is to be performed.|f the lconGroup 
parameter is set to the act_on_all value or the ig=a value (or if the 
parameter is not set), the actions are performed once.If the /conGroup 
parameter is set to the once_per_argument value or the ig=i value, the 
actions are run once per icon. 

Example 


The following directory rules cause dragging an icon into a directory window to copy or move 
the file, depending on whether the left or the right mouse button is used. In each case the 
%P1 sequence is replaced by the path name of the file dropped, and the %PO sequence by 
the path name of the directory window into which it was dropped. 
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directory _rules 


{ 
drop_in_action : dl 
{ 
once_per_ argument; 
actions { 
desktop : copy_into %P0 $%Pl 
} 
} 
drop_in_action : d2 
{ 
once_per_ argument; 
actions { 
desktop : move_into %P0 %Pl 
} 
} 
} 


An important difference to note between the icon group options is the action taken when 
several icons are triggered at the same time. With the once_per_argument (ig=i) value, the 
action list is duplicated several times, one copy for each icon dropped, and then each copy is 
modified by the substitution system to include details about that icon. 


Suppose the action list is as follows: 


actions 


{ 
d : mvi /waste %Pl : 
b : echo %P1 >>/waste/.filelist 


and the /fred/fred, /fred/jim, and /fred/sheila icons are dropped. Because the %P1 
sequence is replaced by the path name of the icon dropped, the action list actually run is: 


actions 
{ 
desktop : move_into /waste /fred/fred ; 
background : echo /fred/fred >>/waste/.filelist 
desktop : move_into /waste /fred/jim ; 
background : echo /fred/jim >>/waste/.filelist 
desktop : move_into /waste /fred/sheila ; 
background : echo /fred/sheila >>/waste/.filelist 


} 


icon_rules or ic Keyword 


Purpose 
Syntax 


Description 


Describes the behavior and appearance of files when represented by icons. 
icon_rules { Pattern[/ Class ] { [Picture] [Title] [trigger_action] ... [drop_in_action] ... }} 


The title, trigger_action, and drop_in_action parameters may appear in any order. 


Patterns are file names, optionally containing certain reserved or pattern matching 
characters according to standard AIX pattern matching syntax: 


e The ? character specifies any single character. For example, the a?c pattern includes the 
abc and aac files, but not the abbc file. 
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e The * character specifies any sequence of characters within file names, including none. 
For example, the a*c pattern includes the ac, abc, acbc, and as4hx..06f,s:c files. 


e Placing characters within brackets, as in the [abc] pattern, indicates any one of the 
specified set of characters. 


The set of characters can be abbreviated using the — (minus sign) character to represent 
a range; for example, the A—D pattern is equivalent to the ABCD pattern. Ranges should 
only be between two letters of the same case, or two digits. 


Prefixing the set with a ! (exclamation point) specifies any characters not included within 
the set. For example, the [!A—Za—x]* pattern means any file name beginning with a 
character other than a letter. 


e The / (slash) special file name can appear as a file specification by writing itas / /d 
(files called slash that are directories). 


Classes represent the properties of files in a concise form. These properties fall into four 
sets as follows: 


e File type 

e Execute permission 

e Read-write permissions 
e Ownership 


A file has exactly one property of each set. Each property is represented by a letter (of either 
case). 


The meanings of the class letters are as follows: 


File type 
B Block special file. 
Cc Character special file. 
D Directory. 
F Regular file. 
G Ghost (non-existent) file. (Implies the H, N, and O classes, described 
below). 
l inaccessible file. (Implies the H, N, and O classes, described below) 
P Pipeline. 
S) Symbolic link to a non-existent file. (Implies the H, N, and O classes, 


described below). 
Execute Permissions for Files 


X User can run the file. 
A File has run permission for someone, but not for the user. 
N No one can run the file 


Execute Permissions for Directories 


X User can list the contents of the directory. 
A Someone, but not the user, can list the contents of the directory. 
N No one can can list the contents of the directory. 
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Read/Write Permissions for Files 


WwW 
Vv 


K 
H 


User can read and write the file. 


User can read but not write the file, and the file has write permission 
for someone. 


User can read the file, and no one can write to the file. 


User can not read the file. 


Read/Write Permissions for Directories 


W 
V 


K 

H 
Ownership 

M 

Oo 


User can read from and write to the directory. 


User can read from but not write to the directory, and the directory has 
write permission for someone. 


User can read from the directory, and no one can write to it. 


User can not read from the directory. 


User owns the file. 


User does not own the file. 


The class strings are interpreted according to the following rules: 


e The order of letters is not significant. 


e Redundant letters are ignored. 


e lf multiple letters from a set appear, the class includes files whose properties match any of 
the classes. For example, tie BCNWVO class is interpreted as the ’(B or C) and N and 
(W or V) and O’ classes. 


e If no letters of a set appear, the class is interpreted as if they all appeared. For example, 
class D is the same as DXANWVKHMO (both mean ’all directories’). 


A number of other codes can also be used in classes. Each stands for a common 
combination of the standard codes: 


Q 
E 
U 
L 
R 


G, |, or S (not a real file). 

X or A (can be run by somebody). 

Aor N (can not be run by the user). 

V or K (can be read but not written by the user).. 
W or L (can be read by the user). 


For example, the DEO and DAXO classes have the same meaning. 


The following classes are the most useful in rule files: 


D 

F 

FE 
FX 
FN 
FNW 


Directories. 

Files. 

Executable files. 

Files executable by the user. 
Data files. 

Data files that the user can alter. 
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FNT Data files that the user can read.. 


Directory rules in local rules files apply to the directory window of the directory holding the 
rule files. Directory rules in other rule files apply to all directories. 


Parameters 
Pattern Specifies the file names to which the subsequent rules apply. 


Class Specifies a file or group of files to which the subsequent rules apply. It is 
usually clearer to group all the rules that apply to one group of files together. 
The pattern and class definitions must be separated by a space. 


Picture Specifies the name of the bitmap file to be used for the icon. There should 
be at most one Picture parameter. 


Title Specifies the title text displayed for the icon. 
Trigger_action Specifies actions clauses to be performed when the user triggers the icon. 


Drop_in_action Specifies actions clauses to be performed when the user drops other icons 
into a directory with the same name as this icon. 


Examples 
1. The following example defines icons and titles for the calculator, clock, and editor 
programs, and causes the editor program to be run for any file icons dragged onto its 
icon, with those files loaded in ready for editing: 


icon_rules 
{ 
xcale { title =Calculator; picture = xcalc.px } 
xclock { title =Clock; picture = xclock.px } 
xedit 
{ 


title =XEdit; 
picture = quill.px; 


trigger _action : sl {} 
trigger_action : s2 {} 
trigger _action : d2 {} 
trigger _ action : dl { 


actions { background : %P0 %P1 }; 
once _per_ argument } 


} 


2. The next examnle dofines a rule that moves an 


wT we CAL HitwVvuoO ail 


with the left mouse button into that directory: 


” 
~ 
oh 
—e 
we 


tem mbm 


icon_rules 


{ */D 
{ trigger_action : dl 
actions { 
desktop : move_icon %P0 %P*} ; 
act_on_all 
} 
} 
} 
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3. The final example shows a section of the standard definition of the icon rules for the 
Trash icon. The Trash icon is implemented as a directory with a suitable picture and title. 


For convenience, dragging with the left mouse button moves a file to the Trash directory, 
rather than copying it as the usual default. 


The Trash directory can be emptied by double clicking with both mouse buttons. The rm 
-rf %P0/* command deletes all files in the directory. 


icon_rules 


waste /D 
{ 
title =Trash; 
picture =waste.px; 
trigger_action : s3 { actions { background : 
rm —r PO } } 


} 
} 

locked_on_desktop or If Keyword 

Purpose 
Specifies the icons to be locked on the desktop. 

Syntax 

locked_on_desktop { [ FileName ;] ... } 

Description 
Locked files appear on the desktop. The user cannot put them back into the directories from 
which they came. 
Locked file lists in the system and user rule files apply whenever the AlXwindows desktop is 
run. A locked file list in an environment file applies only while that environment file is current. 
Locked file lists are ignored in local rule files. 

Example 


locked_on_desktop 
{ 
/ ; 
/bin : 
/usr/bin; 


} 
menu or me Keyword 


Purpose 
Defines the items on menus and the actions to be carried out when a particular item is 
selected. 

Syntax 
menu : Menu_Name {[ Menu_Item] ... [ Dividing_ Line]... } 

Parameters 


Menu_name _ Specifies the menu name. 
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Dividing_line _ Displays a thick or thin dividing line in place of a menu item on the menu 
when included in a menu rule. The dividing line cannot be selected. Two 
options are available as follows: 
dividing line (dv=n) 
thick_dividing line (dv=t) 


Example 
The following example defines the clean_up menu which puts away selected icons from the 
desktop and closes selected windows: 


menu : clean_up 


{ 


menu_item : put away icons 


{ 


actions { d : put_back_icon %P* } 


dividing line 
menu_item : close windows 


{ 


actions { d : cdw %P* } 
} 
} 
menu_item or mi Keyword 


Purpose 
Specifies an item on a menu and the action to be performed when the item is selected. Used 
only within menu clauses. 


Syntax | | 
menu_item : /temName { [ Actions } } 
menu_item : /temName { [ Pull_off_menu ]} 


Parameters 
ItemName Specifies the name of the menu item as it appears on the menu. 


Actions Specifies actions to be performed when the item is selected. 


Pull_off_menu Specifies a subsidiary menu to appear beside the current menu. 


picture or pi Keyword 


Purpose 

Specifies the bit mapped picture file to be used for the icons for the associated files. 
Syntax 

picture = picture_file 
Description 


The picture file usually has a .px file extension. For example the following means that all 
directories are to use the picture in the picture file dir.px.: 


*/D { picture = dir.px } 
If no picture file is specified, the icon is invisible. 
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pull_off_menu or pm Keyword 


Purpose 
Specifies a menu to appear beside the current menu when the associated menu item is 
selected. 
Syntax 
pull_off_menu = Menu_Name 
Parameter 
Menu_Name Specifies the name of the new menu. It must correspond to a defined menu. 


title or ti Keyword 4 


Purpose 
Assigns a title to the specified icons. 
Syntax 
title =Name 
Description 
All spaces are significant between the equals sign and the semicolon or closing bracket. 
Substitutions can be used to include the actual file name in the title. 
Examples 


1. The following clause: 
xclock { title =Clock} 
sets the title of the xclock program. 


2. If necessary for formatting purposes, new lines, spaces, and tabs can be included before 
and after the icon title. Surrounding unwanted white space with a pair of percent signs 
ensures that it is ignored. The following rule: 


icon_rules { * { title =Title for all icons} } 
is equivalent to: 
icon_rules { * { title =Title % 


for all icons} } 


trigger_action or ta Keyword 


Purpose 
Specifies the actions to be carried out when a specified trigger occurs with the mouse 
pointing to the icon. 

Syntax 
trigger_action : Trigger_ID { [ actions ] [ lcon_Group } } 

Parameters 


Trigger_ID Specifies the trigger for which this action is performed. 


actions Specifies the actions to be performed. Each trigger_action clause can 
contain at most one actions parameter. 


icon group Specifies how many times the action is to be performed. Each trigger_action 
clause can contain at most one icon_group parameter. If the icon_Group 
- parameter is set to the act_on_all or ig=a values (or if the parameter is not 
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Examples 


set), the actions are performed once.|f the icon group parameter is set to 
the once_per—argument or ig=i values, the actions are run once per icon. 


1. The following example: 


trigger_action : sl { actions { b : xclock } } 


shows that the s1 trigger—id (a double click with the left mouse button) runs the xclock 
command. 


If the body is blank, the trigger has no effect. 


. The following example: 


* / D { trigger_action : s3 {} } 


shows that the s3 trigger—id (a double click with both mouse buttons) on a directory does 
nothing. 


. The following example: 


icon_rules 


{ 
*.Cc { picture = csrc.px; } 
* /D 
{ 
picture = dir.px; 
trigger_action : sl { ac { d: ddw %P0 t } } 
} 
{ab]* { title =AB file %BO } 
} 


has these effects: 


e all files whose names end in the .c extension use the picture found in the csrc.px 
bitmap file. 


e all directories use the picture found in the dir.px bitmap file. 


e when any directory is triggered with the s1 trigger, a directory window is opened to 
show that directory in time order. 


e any file whose name begins with the lowercase letters a or b has the AB file icon 
title followed by the base name of the file. 


Using Picture Files with the AlXwindows Desktop 


Rule files can refer to pictures either through absolute path names or relative path names. 
For relative path names, the desktop first examines the picture directory (as indicated by in 
the .Xdefaults mechanism), and then it examines the /usr/include/X11/bitmaps directory. 


For example, if the picture directory is set to the /user/fred/pictures directory and you are 
trying to find the core.pic picture file. The desktop looks for the following files: 


/user/fred/pictures/core.pic 
/usr/include/X11/bitmaps/core.pic 


A picture file specification may have a slash in its name, so that, for example, the desktop 
would look for the patterns/checked.pic picture file as follows: 


/user/fred/pictures/patterns/checked.pic 
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/ust/include/X11/bitmaps/patterns/checked.pic 


Picture files are standard AlXwindows bitmap files, containing configuration items and 
picture data. These items can appear in any order, except that all configuration items must 
appear before all data items. 


Configuration Items 
Each contiguration item must be on a separate line, in the following format: 


#define name value 
The fields must all appear on the same line, with the # sign in the first column. 


The first part of the name field is equivalent to the characters of the picture file’s base name 
that precede the first period. It can only contain letters, numbers, and underscores. For 
example, for the pic.px picture file, the first part of the name would be pic. 


picture.width 

picture.height Must be included. Their values are numbers and indicate the width and 
height of the picture in pixels. If the picture is used for an icon, button, or 
cursor, this is the size of the object. If it is used as a background, the 
picture is tiled across the area; these items are still required to enable the 
desktop to interpret the data items. 


picture_x_hot 

picture_y_hot Must either both be included or both be omitted. They are only used if the 
picture is the data portion of a cursor, and indicate the coordinates within 
the picture where the cursor is actually located. For example, if both 
values are 0, the actual point of the cursor would be the top left corner of 
the picture. 


picture_bg 

picture_fg Must be the names of colors, surrounded by double quotes, giving the 
foreground and background colors of the picture. If the color string begins 
with a # character, the remainder of the color name encodes the actual 
color. The string gives the red, green, and blue components of the color, 
in that order, as one, two, three, or four hexadecimal digits each 
(Components written 5, 50, 500, and 5000 are all the same, and differ 
from 05, 050, and 0005.). For example: 


black is "#000000000000” or "#000" 
white is "#£f££fLLLLLLLE” 
redis "#££££00000000” 


If the color does not begin with a # character, the string’s meaning depends on the 
AlXwindows server. The /usr/Ipp/X11/rgb/rgb.txt file contains a listing of valid color names 
and the information AlXwindows uses in displaying them on the screen. 


If these items are omitted, the desktop reads the default value for the foreground from the 
Xdesktop.filelcon.pixmap.foreground resource and reads the default value for the 
background from the Xdesktop.filelcon.pixmap.background resource. 


Picture Data 
Picture data shows the actual bitmap of the picture, in the format 


static unsigned char picture_bits[ ] = { data} 
The word unsigned can be omitted. 


The data parameter represents the actual data, consisting of a sequence of two digit 
hexadecimal values, each prefixed with Ox and separated by commas. 
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There may be up to 20 such values per line, though it is usual to have 12 values. 

The total number of values is equal to: . 
((picture_width+7)/8)*picture_height 

with 

((picture_width+7)/8) 

values for each row of the picture. The division is rounded down to the next lower integer. 


Each value represents eight consecutive pixels, except for the last value in the row, which 
may represent less. 


The following example represents the picture file for a menu pointer: 


#define menu_d_ width 16 
#define menu_d height 16 
#define menu_d_x_ hot 14 
#define menu_d_y_ hot 5 


#define menu_d_bg "black” 
#define menu_d fg "white” 
static char menu_m_bits[] = { 


0x00, 0x00, 0x00, 0x00, 0x00, 0x00, Ox0e, 0x00, 
Oxfa, Oxlf, 0x02, 0x20, Oxc2, Oxlf, 0x02, 0x02, 
Oxc2, 0x03, 0x02, 0x02, Oxfa, Of01, Oxfe, 0x00 

0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00}; 


Defining Triggers for the AlXwindows Desktop 


This chapter describes how to define the trigger maps, trigger IDs, and resources that the 
AlXwindows Desktop uses to interpret mouse actions. 


To give the desktop the flexibility to work with any type of mouse with from one to five 
buttons, the rules describing mouse actions are usually expressed in terms of triggers rather 
than physical buttons. 


Mapping strings within desktop rule files describe all triggers to be interpreted by the 
desktop. This string consists of a sequence of mappings, separated by semicolons. Spaces 
are ignored within the mapping string. 


Each trigger mapping maps a trigger to a trigger-id string, in the following form: 
TriggerSet = TriggerlD 


where: 
TriggerSet Indicates a list of steps separated by commas, and 
TriggerlD Indicates the letter s or d followed by a number. 


The desktop converts clicks on the mouse buttons first into triggers, and then into trigger ids. 
This mechanism is controlled by three items in the .Xdefaults mechanism: 


e the mapping (a string) 
e the maximum motion (a number of pixels) 
e maximum up time (measured in milliseconds). 


The conversion is accomplished in the following stages: 
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1. The motions and button presses are converted into triggers, controlled by the maximum 
motion and the maximum up time. 


2. The triggers are converted to trigger IDs through the mapping string. 


Most users will not change the trigger to trigger 1D mapping, since it has been optimized 
for the particular mouse supplied with the computer system. On PS/2 systems, the 
mapping has been optimized for a two—button mouse, with the following mapping: 


Button Location 

1 The left mouse button 
2 The right mouse button 
3 Both mouse buttons 


Trigger Sets 
A trigger set is a set of steps made up of closely spaced button presses and releases. The 
trigger includes presses and releases of the indicated mouse buttons, beginning with the first 
button pressed when all buttons are raised, and including all presses and releases until the 
next point when all the buttons are raised. 


A step is labelled by giving the numbers of all the mouse buttons that are depressed at any 
time during the step, no matter what order they are in or how long they are down. 


For example, all three of the following examples would be labelled as 1 and 2, or 12: 
e Press button 1, press button 2, release button 1, and release button 2. 
e Press button 2, press button 1, release button 1, and release button 2. 


e Press button 1, press button 2, release button 2, press button 2, release button 2, and 
release button 1. 


If the mouse pointer moves by a distance greater than the amount indicated in the 
xdesktop.triggers.maxMotion resource, the step is considered a drag; otherwise, itis a 
click. 


Clicks and drags are described by giving the numbers of the mouse buttons, as in 12. 


The steps in a trigger definition are separated by commas. For example, a double click on 
button 2 is described as 2,2. 


If the last step in the sequence is a drag, the trigger is defined as a dynamic trigger, and the 
desktop signifies detection of the drag by changing the cursor to the drag cursor or to the 
multi-drag cursor. Other triggers are defined as static triggers. 


A trigger ends when either no button is pressed for the maximum up time after a step, or at 
the end of a drag, whichever comes first. 


The TriggerID String 
The TriggerlD string identifies the string by which the trigger_action clauses in the rule file 
refer to the trigger. 


The letter s is used for static triggers, such as clicks or double clicks, where the mouse is not 
moved. The letter d is used for dynamic triggers or wen: such as where one icon is 
dropped onto another. 


For example, the usual assignment for a three button mouse is for the three trigger—ids s1, 
s2, and $3 to be double clicks on the left, center, and right mouse buttons, respectively. The 
usual assignment for a two button mouse is that the same trigger—ids refer to double clicks 
on the left button, the right button, and both mouse buttons, respectively. 
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A static trigger can also be used to control the selection of icons. This is done by using one 
of the following codes instead of a trigger id: 


+S If the current icon (the icon under the cursor) is not selected, select it. 
-S If the current icon is selected, deselect it. 

Is Deselect all selected icons; then select the current icon. 

~s If the current icon is selected, deselect it. Otherwise, select it. 


For example, the following string indicates that a double click on button 1 selects the current 
icon in addition to any icons already selected. A double click on button 2 deselects the icon. 


l=+s ; 2=—s 


The desktop ignores trigger id strings containing more than five steps. 


Macro definitions 7 
Macro definitions allow one or more buttons to be abbreviated to a single letter. This allows 
mappings to be made more abstract, and easier to convert for a different number of buttons. 


For example, suppose that you have designed a set of mappings for a three button mouse, 
and that you want to convert it to work on a two button mouse. One way might be to say that 
the center button is represented by using both left and right buttons together. By specifying 
all the mappings in terms of the letters L, C, and R, rather than the numbers 1, 2, and 3, the 
mappings are easier to change (especially since the right button changes from being number 
3 to number 2.) 


A macro definition consists of a set of button numbers, an equals sign, and a single letter. 
That letter can then be used in any future trigger description or macro definition. 


For example, a trigger mapping with three static trigger IDs, three dynamic trigger IDs, and 
three selection control triggers, might be written as follows for a three button mouse: 


1=L : 2=C ; 3=R oN 
L=!s ; C=+s ; R=-s XN 
L,L=s1 : C,C=s2 : R,R=s3 2X 
L=dl ; C=d2 : R=d3 


The backslashes indicate that the mapping is continued on the next line. 
To convert to the two button mouse, change the first line as follows: 

1=L ; 12=c ; 2=R ; \ 
The mapping then becomes equivalent to the following: 


1=!s ;12=+s :2=-S aN 
1,1=s1 ; 12,12=s2; 2,2=s3 a 
l=d1 ; 12=d2 ; 2=d3 


The AlXwindows desktop utilities can be used from shell prompts, within shell scripts, and 
within rule files to manipulate and communicate with the AlXwindows Desktop. 


Desktop Utility Descriptions 
The desktop includes the following AIX utilities which can be included in actions statements 
within rule files or within shell scripts: 


mfyi (for your information) Displays a specified message in a window. You can 
also specify the size and color of the window. 


myni (yes or no input) Displays a simple dialog box, and returns a code indicating 
which button the user pressed. 
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mgti (get text input) Displays a prompt and reads in text. 


tellxdt Passes desktop command language commands to the desktop and 
requests information from the desktop about icons. 


mfyi Utility 


Displays an information message in a window. 


mfyi [ —ToolkitOption... | [ —Option... | [ TextForDisplay ] 


The mfyi utility displays an icon, the information type, and left—justified text within a window. 
The desktop removes the window when the user clicks on the icon to acknowledge the 


Purpose 

Syntax 

Description 
information. 

Flags 


The ToolkitOption parameter values are the standard Xtoolkit command line arguments 


specified in the following list: 


-bg Color 


-fg Color 
-fn Font 


—~geometry Geometry 


—display Host: Display 


—name Name 


-xrm_ ResourceString 


Specifies the border color of the window. The 
/usr/lpp/X11/rgb/rgb.txt file contains a listing of valid color 
names and the information AlXwindows uses in displaying 
them. 


Specifies the color to use for displaying text. 


Specifies the font to be used for displaying normal text. The 
/usr/ipp/X11/defaults/fonts file contains a list of valid font 
names and the information AlXwindows uses in displaying 
them. 


Specities the preferred size and position of the information 
window 


Specifies the X—server to contact. 


Specifies the application name to use when retrieving 
resources. 


Specifies a resource string to be used. This is especially 
useful for setting resources that do not have separate 
command line options. 


Additional options can be specified with the Option parameter.The valid options are: 


—center (or —centre) 


—heilp 


-picture Name 


—transfor %W 


Indicates that the message window is centered on the screen. 
This option overrides the x and y coordinates given ina 
—geometry command line option. This option is not valid if the 
-—override command line option has not been specified. 


Indicates that a brief summary of the allowed options is output 
to standard error. 


Indicates the bit map file name for the icon image. Overrides 
the icon type specified by the —type argument. 


Causes the deskware utility windows to be transient. 
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Return Codes 
0 


Example 


-type Text 


Specifies the type of information and the type of icon to be 
displayed. The Text parameter can have the following values: 
error . 
information 
message 
warning 


Ending through the acknowledge symbol 


1 Ending without displaying information 


mfyi —picture warning.xbm —type warning Warning: Accounting stopped 


In this example, mfyi opens an information window displaying the icon contained in the 
warning.xbm bit map file and the text: "Warning: Accounting stopped”. 


myni Utility 


Purpose 
Displays a simple dialog box. 
Syntax 
Description 
Flags 


myni [ —7oo/kitOption... ] | -Option... ] [ TextForDisplay | 


The myni utility displays a question and two control buttons labeled cancel and confirm. 


The myni utility also returns a code indicated the button on which the user clicked. 


The ToolkitOption parameter values commonly used are the standard Xtoolkit command line 
arguments specified in the following list: 


-bg Color 


-geometry Geometry 


—display Host: Display 


—-name Name 


-xrm ResourceString 


Specifies the border color of the window. The 
/ust/pp/X11/rgb/rgb.txt file contains a listing of valid color 
names and the information AlXwindows uses in displaying 
them. 


Specifies the color to use for displaying text. 


Specifies the font to be used for displaying normal text. The — 
/usr/Ipp/X11/defaults/fonts file contains a list of valid font 
names and the information AlXwindows uses in displaying 
them. 


Specifies the preferred size and position of the information 
window 


Specifies the X—server to contact. 


Specifies the application name to use when retrieving 
resources. 


Specifies a resource string to be used. This is especially 
useful for setting resources that do not have separate 
command line options. 


Additional options can be specified with the Option parameter . The valid options are: 
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-cancel FileName Indicates the bit map file to be used for the cancel button. 


~center (or —centre) Indicates that the message window is centered on the screen. 
This option overrides the x and y coordinates given ina 
-—geometry command line option. This option is not valid if the 
—override command line option has not been specified. 


-confirm FileName Indicates the bit map file to be used for the confirm button. 

—help Indicates that a brief summary of the allowed options is output 
to standard error. 

-no Text If no bit map file has been assigned to the cancel control 
button, indicates the text label for the button. 

-picture Name Indicates the bit map file name for the icon image. Overrides 
the icon type specified by the —type argument. 

-transfor %W Causes the deskware utility windows to be transient. 

-yes Text If no bit map file has been assigned to the confirm control 


button, indicates the text label for the button. 


Return Codes 


0 Ending through the confirm control button 
1 Ending due to internal error 
2 Ending through the cancel control button 


Example 
The following example opens a dialog window with: 


e The icon contained in the bit map file question.xbm 

e The confirm button using the file indicated in the bit map file tick. xbm 
e The cancel button using the file indicated in the bit map file cross .xbm 
e The question: Delete file xyz? 


myni —picture question.xbm —confirm tick.xbm —cancel cross.xbm 
Delete file xyz? 


mgti Utility 


Purpose 

Prompts the user for input and returns the text entered to standard output. 
Syntax 

mgti [ Option... | [ DefaultString | 
Parameters 


The ToolkitOption parameter values commonly used are the standard Xtoolkit command line 
arguments specified in the following list: 


-bg Color Specifies the border color of the window. The 
/usr/ipp/X11/rgb/rgb.txt file contains a listing of valid color 
names and the information AlXwindows uses in displaying 
them. 


~-fg Color Specifies the color to use for displaying text. 
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-fn Font Specifies the font to be used for displaying normal text. The 
/usr/lpp/X11/defaults/fonts file contains a list of valid font 
names and the information AlXwindows uses in displaying 


them. 

—geometry Geometry Specifies the preferred size and position of the information 
window 

—display Host: Display Specifies the X—server to contact. 

-name Name Specifies the application name to use when retrieving 
resources. | 

-xrm ResourceString Specifies a resource string to be used. This is especially 


useful for setting resources that do not have separate 
command line options. 


Additional options can be specified with the Option parameter . The valid options are: 


~center (or —centre) Indicates that the message window is centered on the screen. 
This option overrides the x and y coordinates given ina 
-geometry command line option. This option is not valid if the 
-override command line option has not been specified. 


—help Indicates that a brief summary of the allowed options is output 
to standard error. 

-transfor %W Causes the deskware utility windows to be transient. 
—prompt Prompt Prompts the user for information. 

tellxdt Utility 

Purpose 
Passes desktop command language commands to the desktop and requests information 
from the desktop about icons. 

Syntax 
tellxdt [Name][Query]|[ Command] 

Flags 


lf no parameters are indicated, the tellxdt command displays a usage summary. 


The following Name parameters determine the desktop to which commands or queries are 
seni. ii mone are indicated, the commands are sent to the desktop opened most recently. 


~I Lists the names of all available desktops. 
-a Sends the command to all running desktops. 
-—n name Send the command to the named desktop. 


The following Query parameters request information from the desktop about icons. 


-t FileName Returns the title of the icon for the named file. 

-i FileName Returns the name of the picture file for the file’s icon image. 
~c FileName Returns the class code for the file. 

-—s Number FileName Returns the static trigger action for the numbered trigger. 
~S Number FileName Returns the static trigger action for the numbered trigger, 


performing substitutions. 
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-d Number FileName Returns the dynamic trigger action for the numbered trigger. 


-D Number FileName Returns the dynamic trigger action for the numbered trigger, 
performing substitutions. 


-L Lists all active triggers for the desktop. 


- Accepts commands from standard input until it receives an 
End of File character. 


The Command parameter can be any command in the desktop command language, with the 
appropriate arguments. 


The desktop command language allows certain actions to be carried out within the desktop. 
These actions are mainly concerned with icons, directory windows, and files. 


Desktop command language statements can be included within actions clauses in rule files, 
or invoked from within a shell using the tellxdt command. For example, the following 
command:, 


tellxdt get_out_icon desktop 

places the clock’s icon on the desktop. 

Desktop command language statements have two advantages: 

e They automatically update the desktop. 

e They do not rely on the availability of particular AIX binary files. 


Statements in the desktop command language consist of words separated by spaces. The 
end of a statement is determined by the mechanism that initially generates the statement; for 
example, within a rule file the end of a statement is indicated by a semicolon. A backslash 
causes the subsequent character to be part of the current word, even if it is a space 
character. For example, the following statement contains only two words: 


This\ is\ a\ statement with\ only\ two\ words 


All valid statements begin with either a descriptive statement name or a three letter 
equivalent, followed in some cases by a number of parameters. Some statements require 
an exact number of parameters, and the effect of having the wrong number is undefined. 
Other statements accept any number of parameters. 


\ 
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Chapter 2. AIXwindows Window Management 


Changing the Appearance and Behavior of AlXwindows 
Overview 


You can change the way that windows and menus appear and behave by editing information 
in the window management resource database. This database is built from the following 
sources, listed in order of precedence, low to high: 


e the /usr/lpp/X11/SLANG/app-—defaults/Mwm file (where $LANG represents the value of 
the user’s LANG environment variable). 


e resource_MANAGER root window property or $HOME/.Xdefaults file 
e XENVIRONMENT environment variable or $HOME/.Xdefaults—host file 
e mwm command line options. | 


Entries in the resource database can refer to other resource files for specific types of 
resources. These include files that contain bit maps, fonts, and window management 
specific resources such as menus and behavior specifications, and button and key bindings. 


Information about window management is included in the standard .Xdefaults file format, 
with the mwm resource name and the Mwm class name. In the following discussion of 
resource specifications Mwm and mwm can be used interchangeably. 


The AlXwindows window manager uses the following resource sets: 
Component appearance resources: 


These resources specify appearance resources of window management user interface 
components. They can be applied to the appearance of window management menus, 
feedback windows (for example, the window reconfiguration feedback window), client 
window frames, and icons. 


Specific appearance and Behavior resources: 


These resources specify window management appearance and behavior (for example, 
window management policies). They are not set separately for different window manager- 
user interface components. 


Client- Specific resources: 


These window management resources can be set for a particular client window or class of 
client windows. They specify client-specific icon and window frame appearance and 
behavior. 


Resource identifiers can be either a resource name (in which case the first letter is in 
lowercase) or a resource class (in which case the first letter of the name is in uppercase). If 
the value of a resource is a file name and if the file name is prefixed by “~/”, then it is relative 
to the path contained in the $HOME environment variable (generally the user’s home 
directory). This is the only environment variable that window management uses directly (the 
$XENVIRONMENT environment variable is used by the resource manager). 
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Understanding the AlXwindows Window Management 
Resource Description File 
The AlXwindows window management resource description file contains descriptions of 


resources and functions that are used for window management. It contains descriptions of 
resources that cannot be easily encoded in the defaults files. 


The configFile resource indicates the pathname of the user’s AlXwindows window 
management resource description file. By default, if the file exists, the filename is 
$HOME/.mwmre. 


The following types of resources are described in the file: 


Buttons Window management functions can be bound (associated) with button 
events. 

Keys Window management functions can be bound (associated) with key press 
events. 

Menus Menu panes can be used for the window menu and other menus posted 


with key bindings and button bindings. 


The AlXwindows window management resource description file is a standard text file. Items 
of information in the file are separated by white space (blanks, tabs, and new line 
characters). Blank lines are ignored. 


All strings and characters are interpreted within the file, except for the following information: 
e Strings surrounded by double quotes (”). 
e Single characters preceded by the backslash character (\). 


e Lines in which the first character is an exclamation point (!), which are regarded as 
comments. 


e Text following a pound sign (#), unless the pound sign is preceded by a backslash, which 
are regarded as comments. 


Resource Description File Functions 


Window management functions can be accessed with button and key bindings and with 
window management menus. Functions are indicated as part of the specifications for button 
and key binding sets and menu panes. The function specification has the following syntax: 


Function = FunctionName [FunctionArgument...]... 


The value of the FunctionName parameter is the name of a window management function 
and the FunctionArgument parameter is a list of quoted or unquoted items. 


If a function is specified that is not one of the supported functions, the window management 
interprets it as the f.nop function and does nothing. 


You can indicate which resource types can specify a function and the context in which the 
function can be used.. Function contexts include the following: 


root No client window or icon is selected as an object for the function. 


window A client window is selected as an object for the function. This includes the 
window’s title bar and frame. Some functions are applied only when the 
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window is in its normalized state (such as the f.maximize function) or its 
maximized state (such as the f.normalize function). 


icon An icon is selected as an object for the function. 


If a function is specified in a type of resource that does not support that function or is called 
in a context that does not apply, the function is treated as f.nop. The following table 
indicates the resource types and function contexts in which mwm functions apply: 


Function Contexts Resources 

f.beep root, icon, window button, key ,menu 
f.circle_down root, icon, window button, key, menu 
f.circle_up root, icon, window button, key, menu 
f.exec root, icon, window button, key, menu 
f.focus_color root, icon, window button, key, menu 
f.focus_key root, icon, window button, key, menu 
f. kill icon, window button, key, menu 
f.lower root, icon, window button, key, menu 
f.maximize icon, window (normal) button, key, menu 
f.menu root, icon, window button, key, menu 
f.minimize window button, key, menu 
f.move icon, window button, key, menu 
f.next_cmap root, icon, window button, key, menu 
f.next_key root, icon, window button, key, menu 
f.nop root, icon, window button, key, menu 
f.normalize icon, window (maximized) button, key, menu 
f.pack_icons root, icon, window button, key, menu 
f.pass_keys root, icon, window button, key, menu 
f.post_wmenu root, icon, window button, key 

f.prev_cmap root, icon, window button, key, menu 
f.prev_key root, icon, window button, key, menu 
f.quit_mwm root button, key, menu 
f.raise root, icon, window button, key, menu 
f.raise_lower icon, window button, key, menu 
f.refresh root, icon, window button, key, menu 
f.refresh_win window button, key, menu 
f.resize window button, key, menu 
f.restart root button, key, menu 
f.send_msg icon, window button, key, menu 


f.separator 
f.set_behavior 
f.title 


root, icon, window 
root, icon, window 
root, icon, window 


menu 
button, key, menu 
menu 


~~ 


Specifying Component Appearance Resources for AlXwindows 
Window Management 


The AlXwindows component appearance resources specify the appearance of the 
components of the AlXwindows window management user interface. These resources can 
be applied to the appearance of window management menus, feedback windows, client 
window frames, and icons. 


Resources with the active prefix refer only to frames and icons. 


The syntax for specifying component appearance resources that apply to window 
management icons, menus, and client window frames is the following: 


Mwm* ResourcelD: Value 
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For example, the Mwm*foreground resource is used to specify the foreground color for 
window management menus, icons, and client window frames. 


The syntax for specifying component appearance resources that apply to a particular 
window management component is the following: 


Mwm(* 7ype* Resource!D: Value 
The Type parameter has a value of menu, icon, client, or feedback. 


If menu is specified, the resource is applied only to window management menus; if icon is 
specified, the resource is applied to icons; and if client is specified, the resource is applied 
to client window frames. For example,: 


e The Mwm*icon*foreground resource is used to specify the foreground color for window 
management icons. 


e The Mwm*menu‘*foreground resource specifies the foreground color for window 
management menus. 


e The Mwm‘*client*foreground resource is used to specify the foreground color for window 
management client window frames. 


You can configure separately the appearance of the title area of a client window frame 
(including window management buttons). The syntax for configuring the title area of a client 
window frame is the following: 


Mwmiclient*title* Resource/D: Value 


For example, the Mwm‘*client*title*foreground resource specifies the foreground color for 
the title area. Defaults for title area resources are based on the values of the corresponding 
client window frame resources. 


You can configure the appearance of menus based on the name of the menu. The syntax for 
specifying menu appearance by name is the following: 


Mwm*menu*MenuName* Resource!D: Value 


For example, the Mwm*menu*my_menu*foreground resource specifies the foreground 
color for the menu named my_menu. 


Specifying Specific Appearance And Behavior Resources for 
AlXwindows Window Management 


The AiXwiiGows specific appearance and benavior resources coniroi AiXwindows window 
management policies for all user interface components. 

The syntax for specifying window policies is the following: 

Mwm* ResourcelD: Value 


For example, the Mwm*keyboardFocusPolicy resource specifies the window management 
policy for setting the keyboard focus to a particular client window. 


Specifying Client Specific Resources for AlIXwindows Window 
Management 


The AlXwindows client specific resources specify the appearance and behavior for the icons 
and window frames of a particular client window or class of client windows. 
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The syntax for specifying client-specific resources is the following: 
Mwm*ClientName* Resource!lD 

or, 

Mwmi* Class* Resource!lD 


For example, the Mwm*aixterm*windowMenu resource specifies the window menu to be 
used with aixterm clients. 


The syntax for specifying client-specific resources for all classes of clients is 
Mwm‘* ResourcelD: Value 


Individual client specifications take precedence over the general specifications for all clients. 
For example, the Mwm*windowMenu resource specifies the window menu to be used for 
all classes of clients that do not have a window menu specified. 


The syntax for specifying resource values for windows that have an unknown name and 
class (that is, windows without an associated WM_CLASS property) is the following: 


Mwm* Defaults* Resource!D: Value 


For example, the Mwm*defaults*iconlmage resource specifies the file name of the icon 
image to be used for windows that have an unknown name and class. 
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Chapter 3. AlXwindows Toolkit 


AlXwindows Toolkit Overview for Programming 


The AlXwindows Toolkit is a collection of C language data structures and subroutines stored 
in an AlXwindows library named the libXm.a library. The tools in this library simplify the 
creation of interfaces for X11 client applications running in an X-Windows environment. 
These tools are based upon (and often call upon) the X-Windows Toolkit, a graphic toolkit 
that provides direct access to the lower levels of the AIX operating system. One obvious 
consequence of this interaction is that the naming conventions established for the 
AlXwindows Tooikit parallel those established for the X-Windows Toolkit. Together, these 
two toolkits provide a consistent and effective means of generating graphical objects and 
combining them to create AlXwindows interfaces. 


Object Oriented Data Structures 


AlXwindows data structures are object oriented. This means that they describe related 
classes of simple graphical objects. These object classes are called widget classes or 
gadget classes depending upon the interactive options they support. Each graphical object 
generated from these data structures contains appearance intormation, behavioral 
information (information concerning the general behavior of each widget or gadget), and 
state information (information that determines the initial state of each widget or gadget). The 
AlXwindows Toolkit helps you combine individual instances of various widget and gadget 
classes into compound interactive objects containing several widgets and gadgets. These 
objects are the foundation of each AlXwindows interface. They provide the sophisticated 
visual cues necessary for ongoing user interaction. 


Widget classes and gadget classes are arranged in a formal hierarchy. Each class shares a 
common set of resources to which it adds resources inherited from the classes that precede 
it in the hierarchy. This organizational approach conserves data storage space and reduces 
related overhead while maintaining a standard look and feel for AlXwindows interfaces. 


Object Oriented Subroutines 


In addition to widget class data structures and gadget class data structures, the AlXwindows 
Toolkit also provides object oriented subroutines with which to create, alter, and manipulate 
AlXwindows objects. These subroutines are divided into the following categories: 


e Creation Subroutines 
e Convenience Creation Subroutines 
e Support Subroutines 


Understanding AlXwindows Toolkit Naming Conventions 


Prefixes 


The naming conventions associated with the AlXwindows system and the AlXwindows 
Toolkit directly parallel X-Windows naming conventions. The following conventions are used 
to name AlXwindows tools and related software: 


The Xm prefix is the primary AlXwindows name-space identifier. It is used for the following 
names: 


e AlXwindows subroutines 
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e AlXwindows widget—gadget class names and instance pointers (Class pointers use the 
xm prefix as a name-space identifier.) 


e AlXwindows versions of AlXwindows string macros (an N is appended to all resource 
name prefixes; a C is appended to all resource class name prefixes; an R is appended to 
all resource type prefixes.) 


e AlXwindows include directories (directories that contain include files and global | 
definitions) 


e AlXwindows libraries containing include directories 
e AlXwindows defines and callback reasons. 


The XmN prefix is reserved for resource names, classes, and types. The Xt prefix identifies 
X—Windows subroutines and data structures. 


Suffixes 
e The .h suffix identifies include files. 
e The P.h suffix identifies private include files. 


Other Naming Conventions 
e Spaces are removed from the names of subroutines, object class names, class pointers, 
instance pointers, and structures, as well as resource names, classes, and types. The 
character following each removed space is capitalized. 


e Spaces are replaced by underscores in defines names and callback reasons. All other 
letters (except the m in the prefix) are capitalized. 


Examples of Naming Conventions 
Specific examples of these AlXwindows naming conventions include: 


Item Example of Name 

subroutine XmCreateArrowButton 
widget/gadget class name XmArrowButtonGadget 
widget/gadget class pointer xmArrowButtonGadgetClass 
String macro (resource name) XmNtopShadowPixmap 
string macro (resource class) XmCTopShadowPixmap 
string macro (resource type) XmRPixmap 

include filenames Xm.h 

include directory /usr/include/Xm 

library containing include directory /usr/lib/libXm.a 

define name XmVERTICAL 

callback reason XmCR_VALUE_CHANGED 
X-Windows subroutine XtGrabKeyboard 

See AlXwindows Widgets and Gadgets Overview for Programming for a detailed description 
of widgets and gadgets. 
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AlXwindows Widgets and Gadgets Overview for Programming 
Individual widgets and gadgets are the building blocks of AlXwindows interfaces. Some 
widgets and gadgets display information interactively. Others display information without 
reacting to keyboard input or mouse input. Some widgets and gadgets can change their 
graphic appearance in response to input and can actively invoke a wide variety of 
appropriate subroutines. Others are passive containers for interactive widgets and gadgets. 


All AlXwindows widgets and gadgets are divided into classes based on shared behavior 
characteristics and appearance characteristics. These characteristics are called resources. 
The shared behavior resources and appearance resources of each class are passed 
downward to every other class beneath it in the class hierarchy. A resource passed from one 
class to another in this manner is said to be inherited by each class that receives it. 


Physically, an object class is a pointer to a specific data structure. An instance of a widget or 
gadget refers to a specific object derived from a general class. (An individual widget or 
gadget is said to be instantiated from its widget class or gadget class when it is created). 


Every instance of an AlXwindows object consists of two data structures: a class data 
structure describing the appearance and behavior resources of every object in the class and 
an individual data structure describing additional properties of the specific widget or gadget 
itself 


Every AlXwindows object can be customized to some degree by altering the default values 
governing appearance resources such as the size of the object, the size, thickness, and 
shading of its borders, the color of foreground and background elements, and the size and 
style of the text fonts. Resource values are stored in several different locations to promote 
efficiency and increase flexibility. These locations include: 


e Data Structures 


Many resource values are stored as default values in the object class data structures. 
This permits you to apply or alter values at the highest level (the class level). Alteration of 
these resource values automatically affects all subclasses in the hierarchy because they 
inherit the altered resources. 


e Source Code 


Resource values affecting a specific client application can be hard—coded into the 
argument list of each new object instantiated in the source code of that application. 


e Default Files 


Resource values affecting a general class of applications are stored in a single application 
defaults file (the /usr/lib/X11/SLANG/app_defaults file). Resources earmarked for 
customization by individual users typically include lists of resource values in each user’s 
personal defaults file (the $HOME/.Xdefaults file). 


The AlXwindows Toolkit provides more than 150 subroutines to help you generate, alter, and 
manipulate AlXwindows widgets, gadgets, and the compound objects that can be created 
with them. These subroutines are divided into the following categories based on shared 
functionality: 


e Creation Subroutines 


These subroutines create an instance of the single widget or gadget named in the 
subroutine. One creation subroutine is provided for each instantiable widget class and 
gadget class in the AlXwindows’ Toolkit. Creation subroutines provide access to more 
object resources than do other subroutines. 
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e Convenience Creation Subroutines 
These subroutines create an instance of the compound object named in the subroutine. 
e Support Subroutines 


These subroutines provide a means of altering the appearance, functionality, or 
interactivity of objects created with other subroutines. 


Class Hierarchies and Resource Inheritance 
The path of inheritance for the nine basic object classes in the AlXwindows Toolkit begins 
with three X-Windows metaclasses: 


e Object (All AlXwindows objects inherit resources from this metaclass.) 

e RectObject (All rectangular AlXwindows objects inherit resources from this metaclass.) 

e WindowObj (All window—based AlXwindows objects inherit resources from this 
metaclass.). 


These three metaclasses are combined into a single Core class that is the uppermost class 
in the AlXwindows top-level class hierarchy. 


RectObject 
WindowObj 







XmManager 


Figure 1. AlXwindows Top—level 
Class Hierarchy 


No objects are ever instantiated from the Core class; it serves as a supporting superclass 
that provides common resources to all other classes in the hierarchy. 


The next two top-level classes in the hierarchy are layered beneath the Core class. They 
have no other top—level classes beneath them, but each has several subclasses that can 
inherit some or all of the new class resources. Together they provide the primary interactive 
objects required by all AlXwindows interfaces. They are known as: 


e XmGadget (Six subclasses inherit resources from this class.) 
e XmPrimitive (Ten subclasses inherit resources from this class.) 


Each of the six subclasses in the XmGadget class produces gadgets that are the functional 
equivalents of the widgets produced by the XmPrimitive class. Although widgets and 
gadgets are similar in many ways, several significant differences are worth noting. These 
differences include the following: 
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e Windows 


All widgets are window—based objects. They inherit resources from the WindowObj 
class. Gadgets do not inherit the WindowObj class resources (all visual resources must 
be referenced from the parent widget). For this reason gadgets are often described as 
windowless widgets. They do not support the windows, translations, actions, or popup 
children provided by the equivalent XmPrimitive widgets. 


e Overhead 


Gadgets improve relative performance and reduce data storage space requirements 
when compared to widgets. These improvements apply both to client (application) 
processes and server (X—Windows) processes, and are often quite significant. 


Note: Use gadgets instead of their equivalent widgets whenever possible to reduce 
overhead and increase the efficiency of each interface. 
Next in the hierarchy is the following metaclass: 


e Composite (Twenty-five subclasses inherit resources from this class.). 


Like the three metaclasses that make up the Core class, the Composite class does not 
instantiate any widgets. Instead, it provides resources to the subclasses that follow it in 
the hierarchy. 


There are two additional metaclasses directly beneath the Composite class. These 
metaclasses are called: 


e Constraint (Fifteen subclasses inherit resources from this class.). 
e Shell (Eight subclasses inherit resources from this class.) 


The Constraint class is a metaclass that does not instantiate any widgets. Instead, it 
provides common resources to the subclasses that follow it in the hierarchy. 


The Shell class is internal and cannot be instantiated. However, six of the eight subclasses 
beneath the Shell class can be instantiated and provide a means of interfacing with the 
AlXwindows Window Manager. The X-Windows Toolkit provides some of the underlying 
shells, and the AlXwindows Toolkit provides the remaining shells. 


The final top—level class in the AlXwindows hierarchy falls directly beneath the Constraint 
class. Like the Constraint class, it is also a metaclass that acts as supporting superclass for 
the subclasses beneath it. This class is called: 


e XmManager (Fourteen subclasses inherit resources from this class.) 


The XmManager class cannot be instantiated. It supports visual resources, graphics 
contexts, and traversal resources. 


The XmGadget gadget class hierarchy consists of the six following gadget subclasses, each 
of which is essentially equivalent to its like-named XmPrimitive widget subclass: 


e XmSeparatorGadget 

e XmArrowbuttonGadget 

e XmLabelGadget 

e XmCascadeButtonGadget 
e XmPushButtonGadget 

e XmToggleButtonGadget. 
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Each subclass can inherit some or all of the resources of the classes that precede it in the 


hierarchy. 
XmGadget 


XmToggleButtonGadget 


Figure 2. The AlXwindows XmGadget Gadget 
Class Hierarchy 


The XmPrimitive class hierarchy consists of the ten following subclasses (the first six of 
which are essentially equivalent to the like-named XmGadget gadget subclasses): 


e XmSeparator 

e XmArrowButton 
e XmLabel 

e XmCascadeButton 
e XmPushButton 

e XmToggleButton 
e XmList 

e XmScrollBar 

e XmText 

e XmDrawnButton. 


Each subclass can inherit some or all of the resources of the classes that precede it in the 
hierarchy. 


Two of these subclasses (XmList and XmText) are considered specialized subclasses. This 
is because they are inherently more complex to use (and support more sophisticated 
interactivity) than the other subclasses in the XmPrimitive class hierarchy. For example, an 
XmList widget is a general purpose widget that allows you to make a selection from a list of 
items. The application defines an array of compound strings, each of which becomes an 
item in the list. You can set the number of items in the list that are to be visible. You can also 
choose to have the list appear with an XmScrollBar so that you can scroll through the list of 
items. Items are selected by moving the pointer to the desired item and pressing the mouse 
button (or a keyboard key defined as select). The selected item is displayed in inverse color. 
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XmArrowButton 


XmLabel 
= 


XmCascadeButton XmScrollBar 


XmDrawnButton 
XmPushButton 


XmToggleButton 


1 specialized subclass 


Figure 3. The AlXwindows XmPrimitive Widget Class Hierarchy 


Shell widgets typically serve as the parents of the widgets at the top of a client application 
interface widget tree. Most Shell widgets are invisible but have a direct impact on how their 
children are displayed. The Shell widget class hierarchy consists of the eight following 
subclasses: 


TransientShell 
XmDialogShell 
WMShell 
VendorShell 
TopLevelShell 
ApplicationShell 
OverrideShell 
XmMenuShell. 


The classes Shell, WmShell, and VendorShell are considered private because they cannot 
be instantiated. All other subclasses are considered public because they can be instantiated. 
Each subclass can inherit some or all of the resources of the classes that precede it in the 
hierarchy. 


x 
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VendorShell 
TopLevelShell 
ApplicationShell 


OverrideShell 


Figure 4. AlXwindows Shell Widget Class Hierarchy 


TransientShell 


XmDialogShell 


The XmManager widget class hierarchy consists of the following thirteen subclasses: 


e XmScrolledWindow 
¢ XmMainWindow 
e XmRowColumn 
e XmBulletinBoard 
e XmDrawingArea 
e XmPanedWindow 
e XmFrame 

e XmScale 

e XmForm 

e XmMessageBox 
e XmSelectionBox 
e XmCommand 


e XmFileSelectionBox. 


Each subclass can inherit some or all of the resources of the classes that precede it in the 


hierarchy. 


Two of these subclasses (KmRowColumn and XmForm) are considered specialized 
subclasses. This is because they are inherently more complex to use (and support more 


sophisticated interactivity) than the other subclasses in the XmManager class hierarchy. For 
example, an XmRowColumn widget is a general purpose row—column manager capable of 


containing any class of widget or gadget as a child. Although it requires no special 


information about the functioning of its children, it does provide support for several different 
layout styles involving changes in sizing, orientation, packing, children spacing, and margin 


spacing. The three types of menu systems provided by the AlXwindows Toolkit (Popup 
menu systems, Pulldown menu systems, and Option menu systems) are all based upon 
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XmRowColumn widgets configured in different ways (as Popup MenuPanes, Pulldown 


MenuPanes, or as Menu Bars or Option Menus). 


Understanding AlXwindows Creation Subroutines 
There are 30 AlXwindows creation subroutines. Each creation subroutine creates a single 


instance of the widget or gadget named in the subroutine. 


Widget Creation Subroutines 


e XmCreateArrowButton 
XmCreateBulietinBoard 
XmCreateCascadeButton 
XmCreateCommand 
XmCreateDialogShell 
XmCreateDrawingArea 
XmCreateDrawnButton 
XmCreateForm 
XmCreateFrame 
XmCreateFileSelectionBox 
XmCreateLabel 
XmCreateList 
XmCreateMainWindow 
XmCreateMenuShell 
XmCreateMessageBox 
XmCreatePanedWindow 
XmCreatePushButton 
XmCreateRowColumn 
XmCreateScale 
XmCreateScrollBar 
XmCreateScrolledWindow 
XmCreateSelectionBox 
XmCreateSeparator 
XmCreateText 


XmCreateToggleButton. 


Gadget Creation Subroutines 


XmCreateArrowButtonGadget 
XmCreateCascadeButtonGadget 
XmCreateLabelGadget 
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e XmCreatePushButtonGadget 
e XmCreateSeparatorGadget 
e XmCreateToggleButtonGadget. 
Understanding AlXwindows Convenience Creation Subroutines 
Eighteen convenience creation subroutines are included in the AlXwindows Toolkit. These 
subroutines are called convenience creation subroutines because each subroutine 


conveniently creates all of the widgets and gadgets required to make a single instance of the 
compound object named in the subroutine. 


Note: Approximately half of the convenience creation subroutines (those ending with the 
Dialog suffix) are also known as convenience creation dialogs because each creates 
all of the widgets and gadgets required to make a single instance of a specific type of 

‘ compound object called a convenience dialog. 


The following subroutines create convenience dialogs or other compound objects: 
e XmCreateBulletinBoardDialog 
e XmCreateErrorDialog 
e XmCreatelnformationDialog 
e XmCreateFileSelectionDialog 
e XmCreateFormDialog 
e XmCreateMessageDialog 
e XmCreatePromptDialog 
e XmCreateQuestionDialog. 
e XmCreateSelectionDialog 
e XmCreateWarningDialog 
e XmCreateWorkingDialog 
e XmCreateMenuBar 
e XmCreateOptionMenu 
e XmCreatePopupMenu 
e XmCreatePulldownMenu 
e XmCreateRadioBox 
e XmCreateScrolledList 
e XmCreateScrolledText. 
Understanding AlXwindows Support Subroutines 
AlXwindows support subroutines alter the appearance, functionality, or interactivity of the 


objects created with AlXwindows creation subroutines. Support subroutines are divided into 
12 categories based on shared functionality. These categories include: 


e Subroutines that Create and Manipulate Compound Strings 
e Subroutines that Modify XmList Widget Lists 
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e Subroutines that Modify Clipboard Data 

e Subroutines that Grab or Ungrab Keys or the Keyboard 

e Subroutines that Associate an Image With a Name Through Pixmap Caching 
e Subroutines That Provide for Resolution Independence 


e Subroutines That Provide for Protocol Management and Window Manager Message 
Management 


e Subroutines That Support the Keyboard Interface 
e Subroutines that Manipulate Text 

e Subroutines that Manipulate Font Lists 

e Subroutines that Perform Miscellaneous Tasks 


e Subroutines That Are Accessed Automatically 


Subroutines that Create and Manipulate Compound Strings 
Compound strings are designed to permit messages and other text to be displayed without 
the necessity of hard—coding language—dependent attributes such as direction, character 
set, and text. The AlXwindows Toolkit subroutines that create and manipulate compound 
strings include: 


e XmCvtStringToUnitType 
e XmString 

e XmStringBaseline 

e XmStringByteCompare 

e XmStringCompare 

e XmStringConcat 

e XmStringCopy 

e XmStringCreate 

e XmStringCreateLtoR 

e XmStringDirectionCreate 
e XmStringDraw 

e XmStringDrawimage 

e XmStringDrawUnderline 
e XmStringEmpty 

e XmStringExtent 

e XmStringFree 

e XmStringFreeContext 

e XmStringGetLtoR 

e XmStringGetNextComponent 
e XmStringGetNextSegment 
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e XmStringHeight 

e XmStringinitContext 

e XmStringLength 

e XmStringLineCount 

e XmStringNConcat 

e XmStringNCopy 

e XmStringPeekNextComponent 
e XmStringSegmentCreate 

e XmStringSeparatorCreate 

e XmStringWidth. 


Subroutines that Modify XmList Widget Lists 
The following AlXwindows subroutines modify the lists displayed within XmList widgets: 


e XmListAdditem 

e XmListAdditemUnselected 
e XmListDeleteltem 

e XmListDeletePos 

e XmListDeselectAllitems 
e XmListDeselectitem 

e XmListDeselectPos 

e XmListltemExists 

« XmListSelectltem 

e XmListSelectPos 

e XmListSetBottomitem 
e XmListSetBottomPos 
e XmListSetHorizPos 

e XmListSetitem 

e XmListSetPos. 


Subroutines that Modify Clipboard Data 
The AlXwindows Toolkit provides a clipboard to hold data that is being transferred between 
applications. The following cut and paste subroutines permit you to modify the type of data 
on the clipboard or the value of data on the clipboard: 


e XmClipboardCancelCopy 


XmClipboardCopy 


XmClipboardCopyByName 
XmClipboardEndCopy 
XmClipboardEndRetrieve 


3-12 AIX User Interface Programming Concepts 


e XmClipboardinquireCount 
e XmClipboardinquireFormat 
e XmClipboardIinquireLength 
e XmClipboardinquirePendingltems 
e XmClipboardLock 

e XmClipboardRegisterFormat 
e XmClipboardRetrieve 

e XmClipboardStartCopy 

e XmClipboardStartRetrieve 

e XmClipboardUndoCopy 

e XmClipboardUnlock 


e XmClipboardWithdrawFormat. 

Subroutines that Grab or Ungrab Keys or the Keyboard 
The AlXwindows Toolkit provides four subroutines that isolate and redirect keyboard events 
within a widget hierarchy. These subroutines call equivalent X-Windows subroutines to 
accomplish their purpose, but the equivalent subroutines should not be used directly. If they 


are used, the AlXwindows system is not notified of grabs or ungrabs and cannot process 
them correctly. 


XtGrabKey 
XtUngrabKey 
XtGrabKeyboard 
XtUngrabKeyboard. 


Subroutines that Associate an Image With a Name Through Pixmap Caching 
The AlXwindows Toolkit provides four pixmap caching subroutines to enable you to 
associate each bit-mapped image with a name. This association, once established for all 
widgets that have pixmap resources, permits the generation of pixmaps through references 
to a .Xdefaults file (by pixmap name) and through a list of parameters (by pixmap image). 
The AlXwindows system automatically maintains a cache of all pixmaps to improve 
performance and reduce data storage requirements. The following subroutines facilitate the 
process of associating each bit-mapped image with a name: 


e Xminstallimage 
e XmUninstalllmage 
e XmGetPixmap 
e XmDestroyPixmap. 
Subroutines That Provide for Resolution Independence 
All widgets in the AlXwindows Toolkit support a mechanism called resolution independence 
that allows client applications to create and display images that are the same physical size 
regardless of the resolution of the display. Resolution independence ensures that . 


AlXwindows interfaces are compatible with a wide range of systems and display screens. 
The following subroutines are instrumental in the creation of resolution independent widgets: 
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e XmSetFontUnit 


e XmConvertUnits. 


Subroutines That Provide for Protocol Management and Window Manager Message 
Management 
The AlXwindows Toolkit provides a set of inter—client communication subroutines that 
augment the X-Windows protocols and subroutines. The following AlXwindows Toolkit 
subroutines provide for protocol management and window manager message management: 


e XminternAtom 

e XmAtomToName 

e XmAddProtocols 

e XmRemoveProtocols 

e XmActivateProtocol 

e XmDeactivateProtocol 

e XmAddProtocolCaliback 

e XmRemoveProtocolCallback 


e XmSetProtocolHooks 


Subroutines That Support the Keyboard Interface 
The AlXwindows keyboard interface provides for interaction with a client application through 
a keyboard as well as (or in place of) a mouse. The keyboard interface includes keyboard 
focus and traversal as well as keyboard input processing for individual widgets. AlIXwindows 
uses the the concept of tab groups to organize XmPrimitive widgets for more efficient 
traversal within and between groups. The following subroutines provide a means of defining 
tab groups within an application: 


e XmAddTabGroup 


e XmRemoveTabGroup. 


Subroutines that Manipulate Text 
The following subroutines manipulate the text contained in XmText widgets: 


e XmTextClearSelection 
e XmTextGetEditable 

e XmTextGetMaxLength 
e XmTextGetSelection 
e XmTextGetString 

e XmTextReplace 

e XmTextSetEditable 

e XmTextSetMaxLength 
e XmTextSetSelection 
e XmTextSetString. 
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Subroutines that Manipulate Font Lists 
. The following AlXwindows Toolkit subroutines manipulate font lists: 


Subroutines that Perform Miscellaneous Tasks 


XmFontListAdd 
XmFontListCreate 


XmFontListFree. 


The following AlXwindows Toolkit subroutines perform tasks that are described in the 


reference material for each subroutine: 


XmCascadeButtonHighlight 
XmCommandAppendValue 
XmCommandeError 
XmCommandGetChild 
XmCommandSetValue 
XmFileSelectionBoxGetChild 
XmFileSelectionDoSearch 
XmGetMenuCursor 
XmMainWindowSept1 
XmMainWindowSep2 
XmMainWindowSetAreas 
XmMenuPosition 
XmMessageBoxGetChild 
XmOptionButtonGadget 
XmOptionLabelGadget 
XmResolvePartOffsets 
XmScaleGetValue 
XmScaleSetVaiue 
XmScrollBarGetValues 
XmScroliBarSetValues 
XmScrolledWindowSetAreas 
XmSelectionBoxGetChild 
XmSetMenuCursor 
XmToggleButtonGadgetGetState 
XmToggieButtonGadgetSetState 
XmToggleButtonGetState 
XmToggleButtonSetState 
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e XmUpdateDisplay 
e XmisMotifWMRunning 


Subroutines That Are Accessed Automatically 
Additional functionality is provided by internal AlXwindows subroutines and environment 
parameters that are accessed automatically as required. Specific areas of automatic 
functionality include: 


e Setting Resource Defaults Dynamically 


An internal processing subroutine incorporated into each widget resource set permits 
widgets to set all color and pixmap default resource values dynamically (when the widgets 
are created at run time) rather than statically (in the object code). Color and pixmap resource 
defaults are set to black and white for a monochrome system, or to a default color scheme 
(or a color scheme based on the XmNbackground resource) for a color system. These 
subroutines set the foreground color and two shading colors automatically once the 
background color is specified. 


e Using Localized Resource Defaults Files and Environmental Parameters 


The AlXwindows system can make use of localized resource defaults files. In general, 
AlXwindows searches the following locations for resource default values in the following 
order: 


1. Resource default values that are hard-coded within the client application C language 
code have top priority and take precedence over all other defaults. 


2. Resource defaults files that are stored in the /usr/lib/X11/$LANG/app_defaults directory 
have secondary priority. (The names of these files are specified as parameters of the 
Xtinitialize subroutine.) 


3. An .Xdefaults file that is stored in the home directory ($HOME) of any given user is given 
priority only if no other defaults files are encountered. 


The X-Windows Xtinitialize subroutine determines the proper path to the localized resource 
defaults parameters. 


e Using Global Parameters to Store Version and Revision Values 


The AlXwindows XmUseVersion parameter is a global parameter. It is automatically set to a 
value equal to the current version value multiplied by 1000 plus the current revision value. 
(These values are returned by the XmVersion macro during the initialization of the widget 
classes for each interface.) 


Understanding AlXwindows Protocol Management Subroutines 
A protocol is a 32-bit tag that facilitates interactive communication. In the AlXwindows 
system, client applications communicate with the AIX window manager through the use of a 
protocol that is either an X Atom or an arbitrary long integer parameter whose value is 
shared by the parties to the protocol communication. 


Protocol Management 
The AlXwindows Toolkit contains several protocol management subroutines. These 
subroutines provide a means of interacting with properties that contain atom arrays, client 
messages, and associated callbacks. These subroutines support the existing entries for the 
WM_PROTOCOLS property (for predefined ICCC protocols) and the 
_MOTIF_WM_MESSAGES property (for the window manager). 
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Note: Use the AlXwindows subroutine XminternAtom to convert a string 
(motif_wm_messages) to a 32-bit tag and obtain a corresponding X Atom 
(_MOTIF_WM_MESSAGES). 


The window manager sends protocol messages in the form of client application message 
events with the message_type fields of ClientMessage set to the properties and the 
data.I[0] fields set to the protocols. This permits the client application to associate a callback 
list with the protocol that is invoked when each client message event is received. 


Each shell can have one protocol manager per associated property. This protocol manager 
provides the following services: 


e Tracks the state of the protocols, whether they are active or not. 
e Tracks the state of the Shell, and creates and updates the protocol property accordingly. 
e Processes client application messages and invokes the appropriate callbacks. 


Each protocol manager can have multiple registered protocols, and each protocol (identified 
by its own tag) can have any number of associated client application callbacks in addition to 
pre—hook and post—hook callbacks (typically registered by the widget set). 


Each client application uses the _MOTIF_WM_MESSAGES property to indicate to the 
window manager which messages it is currently handling. A client can add £.send_msg 
entries to the menu in one of the following ways: 


e Through use of the $HOME/.mwmnrc file 
e Through use of the XmNmwmMenu resource in the VendorShell class. 


Note: XmNmwmMenu is a string that is parsed by the window manager to determine 
what to display in the system menu and how to react to the selection of each 
menu item. 


Protocol Management Macros 
Each of the five general protocol manager subroutines has a corresponding macro. These 
macros are identified by the uppercase letters WM in their name. The primary difference 
between a general protocol manager subroutine and its corresponding macro is that the 
subroutine is passed a protocol property in all calls while the macro always forces this 
property to WM_PROTOCOLS. 


Note: General protocol manager macros can be quite useful when a client application must 
interact with ICCC protocols such as WM_DELETE_WINDOW or 
WM_SAVE_YOURSELF. 


Protocol State Information 
It is sometimes useful to allow a protocol’s state information (such as its callback lists) to 
persist, even if the client application resigns temporarily from the interaction. The main 
reason to do this is to gray out £.send_msg labels in the system menu. This is supported 
by allowing a protocol to be in one of the two following states: 


e Active 
e Inactive 


If the protocol is active and the shell is realized, the property contains the protocol atom. If, 
however, the protocol is inactive, the protocol atom is not present in the property. 
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Protocol Callbacks 
When the protocol manager receives a client application message associated with a 
protocol, the manager first determines whether the protocol is active or inactive. If the 
protocol is active, every callback associated with the protocol is called. 


Three types of callback lists can be associated with a protocol, including the following: 


e Pre—hook callback lists are intended for AlXwindows Toolkit use and are accessed by the 
XmSetProtocolHooks subroutine. 


e Post-hook callback lists are intended for AliXwindows Toolkit use and are accessed by the 
XmSetProtocolHooks subroutine. 


e All other callback lists are for client use. They are accessed by the 
XmAddProtocolCallbacks subroutine and the XmRemoveProtocolCallbacks 
subroutine. 


Related Information 
Additional information on the use of the $HOME/.mwmrc file can be found under 
Resource Description File Functions in Chapter 2. 


For information about the AlXwindows desktop and the window manager associated with 
AlXwindows interfaces, refer to ALX General Programming Concepts for IBM RISC 
System/6000. 


Reference information on the VendorShell Widget Class and the VendorShell Resource 
Set is located in the User Interface Volumns(3 and 4) of A/X Calls and Subroutines 
Reference for IBM RISC System/6000. 


How to Create an Application Interface with the AlXwindows 
Toolkit 


Prerequisite Tasks or Conditions 
None. 


Procedure 
There are nine basic tasks involved in creating a client application interface using the 
widgets, gadgets, and subroutines in the AlXwindows Toolkit. 


Note: Tasks 1-3 and 7-9 must be completed once for each interface. Tasks 4-6 must be 
repeated once for each obiect in the interface. 


Task 1 Identify and include required header files 
Related Functions: 


#include <X11/Intrinsic.h> 
#include <Xm/Xm.h> 
#include <Xm/widget.h> 


Task 2 Initialize theX-Windows Toolkit Xt Intrinsics 
Related Function: 
Xtinitialize(...) 

Task 3 Add additional top-level windows. 
Related Function: 
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XtAppCreateShell(...) 
Task 4 Set up parameter lists for each widget and gadget in the interface 
Related Function: 
XtSetArg(...) 
Task 5 Add appropriate callback routines. 
Related Function: 
XtAddCallback(...) 
Task 6 Create each widget and gadget in the interface. 
Related Functions: 


XtCreateManagedWidget( 
followed by 
XtManageChild( widget) 


Task 7 Realize all widgets and gadgets. 
Related Functions: 


XtRealizeWidget(parent) 
XtMainLoop() 


Task 8 Compile source code and link all relevant libraries 
Related Function: 


cc +Nd2000 +Ns2000 —oapplication application.c -lXm —IXt -1X11 -IPW 
Task 9 Create appropriate resource defaults files 
Related Functions: 


/ust/Ipp/X11/app—defaults/class 
$HOME/.Xdefaults 


Sample Source Code for AlXwindows Programming Examples 
e option.c 


e popup.c 


In addition to demonstrating general AlXwindows programming techniques, these sample 
programs can be used as a foundation for other, more complex AlXwindows interfaces. If 
you have access to the libraries, files, and toolkits required to create AlXwindows client 
application interfaces, you can compile, link, and run these sample programs with or without 
alteration and observe the effects of any changes you make in the source code, defaults 
files, or inherited resources. To create executable files from these sample source code files, 
complete the following steps: 


1. Use an ASCIl text editor such as vi or ed to create and open an empty file (named 
sample1.c or some other appropriate name) in your $HOME directory (or a similar 
directory created for testing new code). 


2. Move the mouse pointer to the head of the first line of source code you intend to 
copy, and then highlight the remainder of the code by dragging the pointer over the 
code and releasing the button at the end of the last source code line. (Notice that 
anew menu option, Edit, appears on the menubar when you highlight text in this 
manner.) 


3. Pull the Edit menu down and select the Copy option. 
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4. Make certain that your ASCII editor is in the insert mode. Move the pointer into the 
window containing the empty file. Press the left and right mouse buttons 
simultaneously to transfer a copy of the code segment from the Edit buffer into the 
empty file. 


5. Repeat the copy process until you have a complete source code program, and 
then close the file. 


Note: If a resource defaults file is commented into the beginning of any of the source code 
examples you copy, repeat the copy process, moving the contents of the resource 
defaults file into a new file of their own in the /usr/lib/X11/app-defaults directory. 
This new resource defaults file should have the same basename as the new file 
containing the sample source code. 


6. Create and open a new file named makefile in your $HOME directory (or a similar 
directory created for testing new code) and repeat the copy process as necessary 
to copy the contents of the makefile at the end of the two sample programs into 
the new makefile file. 


7. You are now ready to compile each program by entering the following command: 
make ProgramName 


Do not compile any of the source code files with the make command without first 
determining that all related source files and makefile files are in your $HOME 
directory (or a similar directory created for testing new code). 


Task 1: How to Include Header Files for Interfaces Created with the 
AlXwindows Toolkit 


Prerequisite Tasks or Conditions 


Procedure 


1. Ensure that the include files and other header files that you intend to list in your C 
language source code are available and accessible. 


The first task involved in creating a client application interface is to list several specific 
include files in the /nclude Files section of the client application source code. To accomplish 
this task, complete the following steps: 


1. List the following standard include files in the include file section of the client application 
source code, as demonstrated in the Include Files section of the sample source code: 


- #include <X11/Intrinsic.h> (X-Windows subroutines) 
— #include <Xii/Xiii.ti> (Resource names and defined values) 
~ #include <Xm/XmP.h> (Information for widget writers) 


2. List one pair of the following include files for each widget class name and gadget class 
name you reference in the client application source code: 


— #include <Xm/widget_name.h> 
— #include <Xm/widget_nameP.h> 


3. If the client application interface makes use of protocol management subroutines and 
message management subroutines from the AlXwindows Toolkit, list the following include 
files: 


— #include <X11/Protocols.h> 
— #include <X11/AtomMgr.h> 
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Note: The naming conventions for include files differentiate between public include files 
and private include files. Public files are available for use with general client 
applications. They contain class and record pointers, external variables, resource 
names, and the defined values necessary for a specific client application. Private 
files typically contain class and instance structure definitions, variables, and the 
defined values necessary for writing widgets. 


Task 2: How to Initialize theX-Windows Toolkit Xt Intrinsics 


Prerequisite 


Procedure 


Tasks or Conditions 
1. Ensure that the include files and other header files that you intend to list in your C 
language source code are available and accessible. 


2. Identify and include all appropriate header files, including AlXwindows Toolkit include 
files. 


The second task involved in creating a client application interface is to initialize the Xt 
Intrinsics which are found in the X-Windows Toolkit. The Xt Intrinsics must be intialized 
before making any other calls to the Xtintrinsics subroutines. The Xtinitialize subroutine 
establishes the connection to the display server, parses the command line that invoked the 
application, loads the resource database, and creates a shell widget to serve as the parent 
of your application widgets. 


By passing the command line that invoked your application to IxInitialize, the subroutine can 
parse the line to allow users to specify certain resources, such as fonts and colors, for your 
application at runtime. The Xtlnitialize subroutine scans the command line and removes 
those options. The rest of your application sees only the remaining options. 


There is a second subroutine that may be used to initialize the Xt Intrinsics, the 
XtToolkitinitialize subroutine. This subroutine allows you to decide the tyoe of shell you 
want to use. However, this subroutine only initializes the toolkit; it does not open the display 
or create an application shell. To open the display and create an application shell you must 
use the XtOpenDisplay and XtAppCreateShell subroutines. 


1. Select one of the following initialization subroutines to initialize the Xt Intrinsics: 
e Xtlnitialize subroutine 
e XtToolkitinitialize subroutine. 


2. If you decide to use the Xtinitialize subroutine, add the appropriate Xtinitialize syntax 
statement to the client application source code. No other initialization subroutines are 
required because the Xtinitialize subroutine automatically establishes the connection to 
the display server and creates an ApplicationShell widget parent for the subsequent 
widget tree hierarchy. 


If you decide to use the XtToolkitinitialize subroutine, follow the instructions in step 3. 


3. Add the appropriate XtToolkitinitialize syntax statement to the client application source 
code. 


Note: Unlike the XtlInitialize subroutine, the XtToolkitinitialize subroutine does not 
automatically establish the connection to the display or create an 
ApplicationShell widget parent for widget-gadget children. These tasks are 
accomplished by the subroutines in steps 4 and 5. 
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4. Add the appropriate syntax statement for the XtOpenDisplay subroutine. 
5. Add the appropriate syntax statement for the XtAppCreateShell subroutine. 


Task 3: How to Add Top-Level Windows to an AlXwindows Interface 


Prerequisite Tasks or Conditions 
1. Ensure that the include files and other header files that you intend to list in your C 
language source code are available and accessible. 


2. Identify and include all appropriate header files, including AlXwindows include files. 
3. Initialize the X-Windows Toolkit Xt Intrinisics. 


Procedure 
The third task involved in creating a client application interface is to add one or more top 


level windows to the interface. To accomplish this task, complete the following steps: 


1. Identify all of the top-level window widgets required for the client application interface you 
are coding. Typically, one instance of a Shell widget class or subclass is required for 
each top-level window. 


Note: Top-level window widgets are the widgets at the top level of the widget-instance 
hierarchy in a given interface. They are often referred to as top-level windows or 
independent windows because they manage other widgets but are not managed 
themselves. These windows typically are instantiated from the XmMainWindow 
widget class or the XmMessageBox widget class. 


2. Declare all top-level windows in the Forward Declaration section of your source code. 
3. Create and realize a main Application window. 


4. Develop a widget tree to ensure that all the widgets and gadgets required for the client 
application interface are included in your client application source code. The existing 
ApplicationShell widget should be at the top of the tree 


Note: If you used the Xtinitialize subroutine to initialize the X-Windows Toolkit, an 
ApplicationShell widget was automatically created. If you used the 
XtToolkitinitialize subroutine to initialize that Toolkit, you were required to create 
explicitly an ApplicationShell widget with the XtAppCreateShell subroutine. 


Each client application interface can have several windows. However, each of these 
windows needs to be created as the child of a top-level Shell superclass parent. Since 
only one ApplicationShell widget is permitted per client interface, TransientShell 
widgets or TopLevel widgets must be used for all other tcp-level windows. 


5. List in the appropriate section of the client application source code all widgets and 
gadgets shown in the widget tree. Include an appropriate syntax statement in the client 
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application source code for each top-level window widget, as provided in the reference 
material for each widget class. 


Task 4: How to Set Up Parameter Lists for AlXwindows Widgets and 


Gadgets 


Prerequisite yaa or Conditions 


Procedure 


. Ensure that the include files and other header files that you intend to list in your C 
language source code are available and accessible. 


2. Identify and include all appropriate header files, including AlXwindows include files. 
3. Initialize the X-Windows Toolkit. 
4. Add all top-level windows required for the client application interface. 


The fourth task involved in creating a client application interface is to set up an argument list 
for each widget and gadget in the interface. To accomplish this task, complete the following 
steps: 


1. Determine which of the following variations of the X-Windows XtSetArg macro is most 


appropriate for each widget and gadget in the client application interface: 
Variation 1 


The first line of this variation declares an array named args whose size can range up to 
any predetermined maximum (ten elements in this example). Arrays of this type can be of 
unlimited size as long as the number of elements allocated is greater than or equal to the 
number of elements actually used. The first parameter (subscript 0) specifies the label for 
the created widget. (in this instance the label is actually a pointer to a compound string 
created by a call to a subroutine earlier in the code.) The second and third parameters 
(subscripts 1 and 2) specify that the widget has a width of 250 pixels and a height of 150 
pixels. The following syntax statement defines variation 1: 


Arg args[10]; 

XtSetArg(args[0], XmNlabelString, btn_text); 
XtSetArg(args[{1], XmNwidth, 250); 
XtSetArg(args[2], XmNheight, 150); 


Variation 2 


In this variation, a variable nis declared and used as a counter to to determine the size of 
the array. The use of a counter-variable rather than a hard-coded constant makes it 
easier to add and delete parameter assignments. The variable contains the total number 
of resources that have been set. It can be passed to the XmCreate_ subroutines 
elsewhere in the source code as the parameter list count. The following syntax statement 
defines variation 2: 


Cardinal n=0; 

Arg args[10]; 

XtSetArg(args[0], XmNlabelString, btn_text); n++ 
XtSetArg(args[n], XmNwidth, 250); n++ 
XtSetArg(args[n], XmNheight, 150); n++ 
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Note: Do not increment the counter from inside the call to the XtSetArg macro. As 
currently implemented, the XtSetArg macro dereferences the first argument 
twice. A counter incremented from inside the call is incremented twice for each 
Call. 


. Include an appropriate variation of the XtSetArg macro in every section of the client 
application source code in which a widget or gadget is created, as demonstrated in the 
Create XmWidgetName sections of the sample source code. 


Note: There are three advanced programming alternatives to using the XtSetArg 
macro to set argument values for widgets and gadgets. The first of these is to 
assign each element of the type Arg individually as follows, being sure to keep 


name-value pairs synchronized: 


XmString btn_text; 
Arg args [10]; 
btn_ text = XmStringCreateLtoR (Push Here, 
XmSTRING_ DEFAULT _CHARSET) ; 


args[0].name = XmNwidth; 
args[0].value = (XtArgVal) 250; 
args[{1].name = XmNheight; 
args[1].value = (XtArgVal) 150; 
args{2].name = XmNlabelString; 


args{2].value = (XtArgVal) btn_text; 


The second alternative to using the SetArg macro is to initialize argument lists statically 
at compile time as follows: 


static Arg Args [] = { 
{XmNwidth, (XtArgVal) 250}, 
{XmNheight, (XtArgVal) 150}, 
}; 


The values of each argument are cast to the XtArgVal variable type. When the widget 
creation subroutine is invoked, the XtNumber(args) macro returns the number of 
elements in the argument list. You can create any number of lists as long as you declare 
each list as an Arg variable type. 


The final alternative for creating argument lists involves initializing a list statically at 
compile time (as previously shown), and then modifying the values of the settings using 
regular assignment statements as follows: 


XmString btn_text; 
static Arg Args [] = { 
{XmNwidth, (XtArgVal) 500}, 
{XmNheight, (XtArgVal) 150}, 
{XmNlabelString, (XtArgVal) NULL}, 
};btn_text = XmStringCreateLtoR ( Push Here , 
XmSTRING_ DEFAULT _CHARSET) ; 


args[{1].value 
args[2].value 


(XtArgVal) 250; 
(XtArgVval) btn_string; 


Task 5: How to Add Callback Routines 


Prerequisite Tasks or Conditions 


1. Ensure that the include files and other header files that you intend to list in your C 
language source code are available and accessible. 


2. Identify and include all appropriate header files, including AlXwindows include files. 
3. Initialize the X-Windows Toolkit Xt Intrinisics. 
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Procedure 


4. Add all top-level windows required for the client application interface. 
5. Set up parameter lists for all widgets and gadgets used in the client application interface. 


The fifth task involved in creating a client application interface is to create specific callback 
procedures and add callback lists for interactive widgets and gadgets. To accomplish this 
task, complete the following steps: 


1. Identify each widget and gadget that can be involved in an interactive event such as a 
mouse button press, a keyboard selection, or a cursor movement. 


2. In the client application source code include the callback procedure to be invoked in 
response to each of these interactive events. Use the following syntax statement for each 
callback procedure: 


void CallbackProc (w, client_data, call_data) 
Widget w; 

caddr_t client_data; 

caddr_t call_data; 


where the parameters have the following values: 
w Specifies the widget-gadget for which this callback routine is invoked. 


client_data Specifies the data that the widget-gadget passes back to the client 
when the widget-gadget invokes the callback procedure. Provides a 
means by which a client can define client-specific data to be passed to 
it, such as a pointer to additional information about the widget-gadget, 
a reason for invoking the callback, and so on. 


Note: The client_data parameter is set to NULL when all necessary 
callback information already exists in the widget-gadget data 
structure. 


call_data Specifies callback-specific data that the widget-gadget passes to the 
client. 


Note: The client_data parameter is also widget-specific. It is set to 
NULL unless otherwise stated in the related widget-gadget 
reference material. 


3. Use the X-Windows XtAddCallback subroutine to create a caliback routine for the first 
user action. Use the following general syntax for this callback routine: 


void XtAddCallback(w, callback_name, callback, client_data) 
Widget w; 

String callback_name; 

XtCallbackProc callback; 

caddr_t client_data; 


where the parameters have the following values: 


w Specifies the widget-gadget data structure to which the callback 
routine should be added. 


callback_name Specifies the callback list (within the widget-gadget) to which the 
callback routine should be appended. 


callback Specifies the callback procedure to add. 


client_data Specifies the client data to be passed to the callback when it is 
invoked by theX-Windows XtCallCallbacks subroutine. The 
client_data parameter is often set to NULL. 
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4. 


Continue building one or more lists of callback routines by using the X-Windows 
XtAddCallback subroutine to add individual callback routines for each 
previously-identified user action. Keep in mind that you might want a single user event to 
trigger multiple callback routines. 


Note: You can add /ists of callback routines to your source code by using the 
X-Windows XtAddCallbacks subroutine in place of the XtAddCallback 
subroutine. 


. Determine which (if any) widgets and gadgets in the client application interface define 


one or more callback resources. This information is included in the reference material 
associated with each widget-gadget class. 


. Set the value of each applicable resource to the name of the callback list you created in 


step 2. 


Task 6: How to Create Widgets and Gadgets With the AlXwindows 


Toolkit 


Prerequisite Haske or Conditions 


Procedure 


oa fF W ND 


. Ensure that the include files and other header files that you intend to list in your C 
language source code are available and accessible. 


. Identify and include all appropriate header files, including AlXwindows include files. 

. Initialize the X-Windows Toolkit Xt Intrinisics. 

. Add all top-level windows required for the client application interface. 

. Set up parameter lists for all widgets and gadgets used in the client application interface. 
. Add appropriate callback routines for each widget class and gadget class, and develop all 


necessary callback lists. 


The sixth task involved in creating a client application interface is to create individual 
instances of all widgets, gadgets, and compound objects required by the client application 
interface. There are two ways you create widgets: 


1. 


Use the X-Windows XtCreateManagedWidget subroutine to create a widget instance. 
Use the following general syntax for this widget creation routine. 


Widget XtCreateManagedWidget (Name, WidgetClass, Parent, ArgumentList,) 


String Name; 
WidgetClass WidgetClass: 
Widget Parent, 
Arglist ArgumentList, 
Cardinal ArgumentCount; 


where the parameters have the following values: 


ArgumentCount Specifes the number of resource/value pair arguments found in the 
argument list. 

ArgumentList Specifies the argument list used to override the resource defaults. 

Name Specifies the resource name for the created widget. The name is 


used for retrieving resources and if unique values are necessary, 
should not be named the same as a widget that is a child of the 
same parent widget. The only exception to this rule is a child that 
use identical resources. 


Parent Specifies the parent widget ID for the widget to be created. 
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WidgetClass Specifies the widget class pointer for the created widget. 


This subroutine names the newly created widget specified by the Name parameter and 
defines it it be a widget of the class specified by the WidgetClass parameter. The class 
name or the widget name can be used in default files to refer to this widget. The widget’s 
parent is the toplevel shell widget returned by the XtInitialize subroutine. The argument 
list and number of arguments specified by the ArgqumentList and ArgumentCount 
parameters complete the call. This subroutine creates the widget and noitifies its parent, 
so that the parent can control its specific layout. 


The second way to create a widget does not automatically manage the widget. Instead, the 
widget is managed when the widget is displayed. 


2. Each widget has its own XmCreate subroutine associated with it. A XmCreate 
subroutine creates the widget it is associated with but does not manage the widget. The 
new widget is managed using the XtManageChild subroutine. 
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Task 7: How to Realize AlXwindows Widgets and Gadgets 


Prerequisite Tasks or Conditions 
1. Ensure that the include files and other header files that you intend to list in your C 
language source code are available and accessible. 


2. Identify and include all appropriate header files, including AlXwindows include files. 
3. Initialize the X-Windows Toolkit Xt Intrinsics. 
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Procedure 


4. Add all top-level windows required for the client application interface. 


5. Set up parameter lists for all widgets and gadgets used in the client application interface. 


6. Add appropriate callback routines for each widget class and gadget class, and develop 


necessary callback lists. 


7. Create an appropriate for the client application interface. 


8. Create all necessary instances of widgets, gadgets, and compound objects as shown in 


the widget tree. 


The seventh task involved in creating a client application interface is to make the top-level 
widget in the AlXwindows interface widget tree (as well as all children managed by that 
widget) visible. To accomplish this task, complete the following steps: 


1 


Add an X-Windows XtRealizeWidget subroutine to the client application source code. At 
run time, this subroutine realizes (makes visible on screen) the top-level widget in the 
widget tree, as well as all children managed by that widget. The syntax for this subroutine 
is: 
void XtRealizeWidget (Widget) 

Widget Widget; 


where the parameter have the following value: 
Widget Specifies the widget 


Add an X-Windows XtMainLoop subroutine to the client application source code. This 
subroutine causes the client application to enter a loop, awaiting action by the user. The 
application passes control to the Xt Intrinsics and the AlXwindows widgets once the 
XtMainLoop subroutine is called. 


Task 8: How to Link Libraries when Creating an Interface with the 
AlXwindows Toolkit 


Prerequisite ee or Conditions 


Procedure 
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. Ensure that the include files and other header files that you intend to list in your C 
language source code are available and accessible. 


Identify and include all appropriate header files, including AlXwindows include files. 
Initialize the X-Windows Toolkit Xt Intrinsics. 
Add all top-level windows required for the client anolication interface. 


Set up parameter lists for all widgets and gadgets used in the client application interface. 


. Add appropriate callback routines for each widget and gadget, and develop necessary 


callback lists. 


. Create an appropriate widget tree for the client application interface. 


8. Create all necessary instances of widgets, gadgets, and compound objects as shown in 


the widget tree. 


. Realize the top-level widget in the and add the X-Windows XtMainLoop subroutine to 


cause the client application to enter a loop, awaiting action by the user. 


The eighth task involved in creating a client application interface is to link all necessary 
libraries in the appropriate order. To accomplish this task, complete the following steps: 
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1. 


After all source code has been compiled successfully, list these three libraries directly 
after the appropriate link command and flag: 


libX11.a 
libXt.a 
libXm.a 


Note: The order in which you list these libraries is important. Be certain you list the 
libraries in the order shown. 


If the client application source code contains one or more XmFileSelectionBox widgets, 
add the libPW.a library to the link list, placing it between libXm.a and libXt.a as shown in 
the following list: 


libX11.a 
libXt.a 

libPW.a 
libXm.a 


libX11.a 
libXt.a 
libPW.a 
libXm.a 
libIM.a 


. Once all appropriate libraries are listed in the proper order in the link list, they are ready 


to be linked in the normal manner. 


Task 9: How to Provide Resource Defaults Files for Interfaces Created 
with the AlXwindows Toolkit 


Prerequisite Ma or Conditions 


Procedure 
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. Ensure that the include files and other header files that you intend to list in your C 
language source code are available and accessible. 


. Identify and include all appropriate header files, including AlXwindows include files. 

. Initialize the X-Windows Toolkit Xt Intrinsics. 

. Add all top-level windows required for the client application interface. 

. Set up parameter lists for all widgets and gadgets used in the client application interface. 


. Add appropriate callback routines for each widget class and gadget class, and develop 


necessary callback lists. 


. Create an appropriate widget tree for the client application interface. 


. Create all necessary instances of widgets, gadgets, and compound objects as shown in 


the widget tree. 


. Realize the top-level widget in the widget tree and add the X-Windows XtMainLoop 


subroutine to cause the client application to enter a loop, awaiting action by the user. 


10. After the source code has been successfully compiled, link the resulting object code with 


all appropriate libraries. 


The ninth task involved in creating a client application interface is to decide whether or not to 
add one or more resource defaults files to the client application interface. To accomplish this 
task, complete the following steps: 


1: 


Determine whether or not you want to provide the user with resource defaults files that 
permit the user to customize the AlXwindows interface at run time. Consider the following 
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factors when determining whether to specify an argument in a defaults file or in the 
program itself: 


e Using a resource defaults file provides additional flexibility. The user can override 
preset defaults to reflect personal preferences, and the client application resource 
defaults file can also be modified for system-wide customization. 


e Specifying resource defaults settings in the source code rather than a resource 
defaults file gives the programmer greater control over the interface. These resource 
defaults cannot be overridden unless the source code is made available. 


e Using resource defaults files can speed application development. Changes in resource 
defaults can be accomplished with any ASCII text editor, without the need for 
recompilation of source code or relinking of libraries and files. 


e Resource defaults files can simplify the client application source code because 
resources in defaults files are specified as strings. The same resources listed in your 
source code might have to be in some internal format that requires several subroutines 
to compute. 


e Specifying resource defaults in the source code ofien results in more efficient 
performance of the interface due to reduced processing overhead. 


2. You can use two files for customization of the resource defaults: 


/usr/lib/X11/app-defaults/File This file supplies resource defaults for an entire 
class of AlXwindows client applications executing 
anywhere in the computer system. 


Application programs specify the file that contains the application defaults when they call 
the Xtlnitialize subroutine. The ApplicationClass parameter of the XtInitialize subroutine 
specifies the name of the application defaults file. Several applications can point to the 
same file: 


-Xdefaults This file, placed in an individual user’s home 
directory, supplies resource default values for all 
applications started by that user. 


The user defaults override application and system defaults and allow different users 
running the same program to specify their personal display preferences, such as color 
and font selection. 


Note: At run time, AlXwindows checks first for system resource defaults compiled into 
the widgets. then overrides them with the resource defaults in the client 
application defaults file /usr/ib/X11/app-defaults/ File (provided it exists). 
AlXwindows then looks for the .Xdefaults resource defaults file in the user’s 
home directory and (assuming it exists) resets the resource default values as 
necessary. These resource defaults remain operative unless a different resource 
defaults has been hard-coded into the client application source code, in which 
case, the client application resource defaults overrides all resource defaults files. 


Defaults File Interaction Example 
The following example illustrates the interaction of the defaults files with each other and with 
parameters specified in programs. 


To determine the color of the background, the Xt Intrinisics will do the following: 


3-30 AIX User Interface Programming Concepts 


1. Look for the system defaults and initialize the background color to white. (These defaults 
are compiled into the widgets.) 


2. Look for the application defaults file /usr/lib/X11/app—defaults/Fi/e and set the 
background color to the color specified by the file, for example, black. 


3. Look for the user defaults file .Xdefaults and set the background color to the color 
specified by this file, for example, blue. 


4. lf the program sets the background argument, XmNbackground, this overrides any 
defaults that may have been set. 


Related Information 
Chapter 1. AlXwindows Desktop contains information about the purpose of resource 
defaults and the format and contents of defaults files such as 
/usr/lib/X11/app-defaults/application_name and .Xdefaults. 


The User Interface Volumns(3 and 4) of AIX Calls and Subroutines for IBM RISC 
System/6000 contain information about the following: 


e The XmMainWindow Widget Class, XmMainWindow Widget Class, XmMessageBox 
Widget Class, ApplicationShell Widget Class. 


e The XtArgVal variable type and the XtNumber(args) macro, as well as information 
about using the XtSetArg subroutine as a macro. 


e The X-Windows Xtlnitialize Subroutine, XtToolkitInitialize Subroutine, 
XtAddCaliback Subroutine, XtAddCallbacks Subroutine, XtGetValues subroutine, 
XtDestroyWidget subroutine, XtManageChild subroutine, XtManageChildren 
subroutine, XtUnmanageChild subroutine, XtUnmanageChildren subroutine, ' 
XtCreateManagedWidget subroutine, XtMainLoop Subroutine, and XtCreateWidget 
subroutine. 


Sample Source Code for AlXwindows Interfaces 
The makefile at the end of the two sample AlXwindows programs must be used to compile 
these sample programs. 


/* AiXwindows Interface Example #1: option.c */ 
/* list all standard include files */ 
#include <stdio.h> 
#include <sys/signal.h> 
#include <Xm/XmP.h> 
#include <X11/Shell.h> 
/* list an include file for each widget and gadget you use */ 
#include <Xm/BulletinB.h> 
#include <Xm/CascadeB.h> 
#include <Xm/CascadeBG.h> 
#include <Xm/FileSB.h> 
#include <Xm/Frame.h> 
#include <Xm/Label.h> 
#include <Xm/LabelG.h> 
#include <Xm/List.h> 
#include <Xm/MainW.h> 
#include <Xm/MenuShell.h> 
#include <Xm/MessageB.h> 
#include <Xm/PanedW.h> 
#include <Xm/PushB.h> 
#include <Xm/PushBG.h> 
#include <Xm/RowColumn.h> 
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#include <Xm/SelectioB.h> 
#include <Xm/Text.h> 


#define NUM 100 
/* Forward Declarations - beginning with all widgets to be used */ 


Widget _ shell, 
panel, 
btn1, 
btn2, 
btn3, 
label, 
button, 
optionMenu; 


static XtCallbackProc hello1CB(); 
static XtCallbackProc hello2CB(); 
static XtCallbackProc hello3CB(); 


static void die(); 


int n; 
Arg args[NUM]; 
Display *display; 


XmString string; 
/* start main loop - main logic for AlXwindows interface*/ 
void main(argc, argv) 
int argc; 
char **argv; 
/* locals */ 
Boolean __ trace = False; 
/* look for activity */ 
signal(SIGINT, die); 
/* initialize the Enhanced X-Windows toolkit and open display */ 
XtToolkitinitialize(); 
display = XtOpenDisplay(NULL, NULL, argv[0], “window”, 
NULL, 0, &argc, argv); 
if (display == NULL) { 
fprintf(stderr, "%s: Can’t open display”, araqv[01); 
exit(1); 
} 
/* Create Application Shell */ 
n= 0; 
XtSetArg( args{n], XmNwidth, 400 ); n+t+; 
XtSetArg( args[n], XmNheight, 400 ); ntt+; 
XtSetArg( args[n], XmNallowShellResize, True ); n++; 
shell = XtAppCreateShell( argv[0], NULL, applicationShellWidgetCl 
ass, 
display, args, n); 
XtRealizeWidget( shell ); 
n = 0; 
panel = XmCreatePulldownMenu( shell, “panel”, args, n ); 
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n = 0; 
btnl = XmCreatePushButtonGadget( panel, "“btnl”, args, n );} 
XtManageChild( btnl ); 


XtAddCallback( btnl, XmNactivateCallback, hellolCB, NULL ); 


n = 0; 
btn2 = XmCreatePushButtonGadget( panel, "btn2"”, args, n ); 
XtManageChild( btn2 ); 


XtAddCallback( btn2, XmNactivateCallback, hello2CB, NULL ); 


n= 0; 
btn3 = XmCreatePushButtonGadget( panel, "“btn3”, args, n ); 
XtManageChild( btn3 ); 


XtAddCallback( btn3, XmNactivateCallback, hello3CB, NULL ); 
string = XmStringCreate( "options:”, XmSTRING DEFAULT_CHARSET ); 


n = 0; 

XtSetArg( args{n], XmNlabelString, string ); n+t+; 

XtSetArg( args[{n], XmNmnemonic, ‘'m’ ); n++; 

XtSetArg( args[n], XmNsubMenulId, panel ); nt+; 

XtSetArg( args[{n], XmNorientation, XmVERTICAL ); n+t++; 
XtSetArg( args[n], XmNpacking, XmPACK COLUMN ); n++; 
XtSetArg( args[n], XmNentryBorder, 10 ); nt+; 

XtSetArg( args{n], XmNwhichButton, 1 ); n+t+; 

optionMenu = XmCreateOptionMenu( shell, "option”, args, n ); 
XtManageChild( optionMenu ); 


label = XmOptionLabelGadget( optionMenu ); 
button = XmOptionButtonGadget( optionMenu ); 


printf( "ctrl-c to exit \n” ); 


XtMainLoop(); 


} 
Static void die() 
{ 
printf(”"bye ... \n"); 
exit(0); 
} 
static XtCallbackProc hellolCB(w, client_data, call_data) 
Widget w; 
caddr_t client_data; 
caddr_t call data; 
{ 
printf( "hello #1\n” ); 
n= 0; 
XtSetArg( args[n], XmNwhichButton, 1 ); nt++; 
XtSetValues(optionMenu, args, n); 
} 


static XtCallbackProc hello2CB(w, client_data, call_data) 
Widget Ww} 
caddr_t client _data; 
caddr_t call_data; 


printf( "hello #2\n” ); 


n= 0; 
XtSetArg( args[n], XmNwhichButton, 2 ); ntt+; 
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XtSetValues(optionMenu, args, n); 


} 


Static XtCallbackProc hello3CB(w, client_data, call_data) 
Widget Ww; 
caddr_t client_data; 
caddr_t call_data; 


printf( "hello #3\n"” ); 

n = 0; 

XtSetArg( args[n], XmNwhichButton, 3 ); nt+; 
XtSetValues(optionMenu, args, n); 


} 


/* AlXwindows Interface Example #2: popup.c */ 
/* list all standard include files */ 
#include <stdio.h> 
#include <sys/signal.h> 
#include <Xm/XmP.h> 
#include <X11/Shell.h> 
/* list an include file for each widget and gadget you use */ 
#include <stdio.h> 
#include <sys/signal.h> 
#include <Xm/XmP.h> 
#include <X11/Shell.h> 
#include <Xm/BulletinB.h> 
#include <Xm/CascadeB.h> 
#include <Xm/CascadeBG.h> 
#include <Xm/FileSB.h> 
#include <Xm/Form.h> 
#include <Xm/Frame.h> 
#include <Xm/Label.h> 
#include <Xm/LabelG.h> 
#include <Xm/List.h> 
#include <Xm/MainW.h> 
#include <Xm/MenuShell.h> 
#include <Xm/MessageB.h> 
#include <Xm/PanedW.h> 
#include <Xm/PushB.h> 
#include <Xm/PushBG.h> 
#include <Xm/RowColumn.h> 
#include <Xm/ScrollBar.h> 
#include <Xm/ScrolledW_h> 
#include <Xm/SelectioB.h> 
#include <Xm/Text.h> 


#define NUM 100 
/* Forward Declaration - beginning with each widget used */ 


Widget shell; 
Widget bb; 
Widget mbar; 
Widget text; 
Widget __ btn1; 
Widget __ btn2; 


Widget _push1; 
Widget _push2; 
Widget —push3; 
Widget _push4; 
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Widget 1; 
Widget 2; 


static XtCallbackProc button1 call(); 
static XtCallbackProc button2call(); 
static XtCallbackProc button3call(); 
static XtCallbackProc button4call(); 


Display “display; 
static void die(); 


void main(argc, argv) 


int argc; 
char **argv; 


/* locals */ 


int n; 
Arg args[NUM]; 


/* look for activity */ 


signal(SIGINT, die); 


/* initialize the toolkit */ 


- 


ak 


*/ 


/* 


XtToolkitlnitialize(); 
display = XtOpenDisplay(NULL, NULL, argv[0], "window”, 
NULL, 0, &arge, argv); 
if (display == NULL) { 
fprintf(stderr, "%s: Can’t open display”, argv[0}); 
exit(1); 
} 
n=0; 
XtSetArg( args[n], XmNgeometry, ”+600+800” ); n++; 
XtSetArg( args[n], XmNwidth, 300 ); n++; 
XtSetArg( args[n], XmNheight, 300 ); n++; 
XtSetArg( args[n], XmNallowShellResize, True ); n++; 
shell = XtAppCreateShell( argv[0], NULL, 
applicationShellWidgetClass, 
display, args, n); 
XtRealizeWidget( shell ); 


n=0; 

XtSetArg( args[n], XmNx, 50 ); n++4; 

XtSetArg( args[n], XmNy, 50 ); n++; 

XtSetArg( args[n], XmNwidth, 50 ); n++4; 

XtSetArg( args[n], XmNheight, 50 ); n++; 

bb = XmCreateRowColumn( shell, ’rowcol’, args, n ); 
XtManageChild( bb ); 


create the menu pane 


n=0Q; 
mbar = XmCreateMenuBar( bb, menu”, args, n ); 
XtManageChild( mbar ); 


** create the pulldown menus 


st 
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n=0; 
pi = XmCreatePulldownMenu( mbar, popup”, args, n ); 
n=0; 
p2 = XmCreatePulldownMenu( mbar, “popup”, args, n ); 


fr 
** create the cascade buttons 
*/ 
n=0; 
XtSetArg( args[n], XmNsubMenuld, p1 ); n++; 
btn1 = XmCreateCascadeButton( mbar, "casc1”, args, n ); 
XtManageChild( btn1 ); 
n=0; 
XtSetArg( args[n], XmNsubMenuld, p2 ); n++; 
btn2 = XmCreateCascadeButton( mbar, "casc2”, args, n ); 
XtManageChild( btn2 ); 
/* 
** create the pushbuttons for the pulldown menus 
i 
n=0; 


pushi = XmCreatePushButtonGadget( p1, "button1”, args, n ); 
XtManageChild( push1 ); 


XtAddCallback( push1, XmNactivateCallback, buttonicall, NULL ); 


n= 0; 
push2 = XmCreatePushButtonGadget( p1, "button2”, args, n ); 
XtManageChild( push2 ); 


XtAddCallback( push2, XmNactivateCallback, button2call, NULL ); 


n=0; 
push3 = XmCreatePushButtonGadget( p2, "button3”, args, n ); 
XtManageChild( pushs ); 


XtAddCallback( push3, XmNactivateCallback, button3call, NULL ); 


n=0Q; 
push4 = XmCreatePushButtonGadget( p2, "button4”, args, n ); 
XtManageChild( push4 ); 


XtAddCallback( push4, XmNactivateCallback, button4call, NULL ); 
printf “ctri-c to exit \n” }; 


XtMainLoop(); 


static void die() 


printf(”bye ... \n”); 
exit(0); 


static XtCallbackProc button1call( widget, client_data, call_data ) 
Widget widget; 

caddr_t client_data; 

caddr_t call_data; 


{ 
} 


printf( "hello, from button1\n” ); 
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static XtCallbackProc button2call( widget, client_data, call_data ) 
Widget widget; 

caddr_t client_data; 

caddr_t call_data; 


{ 
} 


static XtCallbackProc button3call( widget, client_data, call_data ) 
Widget widget; 

caddr_t client_data; 

caddr_t call_data; 


printf( "hello, from button2\n” ); 


printf( "hello, from button3\n” ); 


static XtCallbackProc button4call( widget, client_data, call_data ) 
Widget widget; 

caddr_t client_data; 

caddr_t call_data; 


printf( "hello, from button4\n” ); 


/* Makefile for Compiling Sample AlXwindows Programs */ 
CFLAGS=-DSTRINGS ALIGNED 
CC=/bin/cc 
RM=/bin/rm -rf 
DEPS= 
LOCAL LIBRARIES= -1PW -1Xm -1Xt -1X11 -1IM 


eC.O8 

$(RM) $@ 

$(CC) -c $(CFLAGS) $*.c 
HHH 


all:: list 


list: list.o 
$(RM) $@ 
$(CC) -o $@ list.o $(LOCAL LIBRARIES) 


clean:: 
$(RM) list 
$(RM) list.o 


all:: option 


option: option.o 
$(RM) $@ 
$(CC) -o $@ option.o $(LOCAL LIBRARIES) 


clean:: 
$(RM) option 
$(RM) option.o 


all:: popup 
popup: popup.o 


$(RM) $@ 
$(CC) -o $@ popup.o $(LOCAL LIBRARIES) 
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clean:: 
$(RM) popup 
$(RM) popup.o 


How to Create Menu Systems with the AlXwindows Toolkit 


Prerequisite Tasks or Conditions 
. Ensure that the include files and other header files that you intend to list in your C 
language source code are available and accessible. 


2. Identify and include all appropriate header files, including AlXwindows include files. 
3. Initialize the Enhanced X-Windows Toolkit. 


4. Add all top—level windows required for the client application interface. 


Procedure 
The AlXwindows Toolkit provides the following three types of menu systems for use in client 
application interfaces: 


e Popup menu systems 
e Pulldown menu systems 
e Optionmenu systems 


Each menu system is based upon an XmRowColumn widget configured to behave in a 
specific manner. To create a menu system for a client application interface, complete the 
following steps in sequential order: 


1. Determine which of the three types of AlXwindows menu systems is best suited for your 
current purpose: 


e A Popup menu system usually consists of a single XnRowColumn widget (configured 
as a Popup MenuPane widget and containing a combination of XmLabel widgets, 
XmPushButton widgets or gadgets, XmToggleButton widgets or gadgets, and 
XmSeparator widgets or gadgets), plus its parent MenuShell. In addition, it can 
contain XmCascadeButton widgets or gadgets that access Pulldown MenuPanes 
functioning as submenus. 


e A Pulldown menu system typically consists of an XmRowColumn widget configured as 
a MenuBar widget , a set of XmCascadeButton widgets or gadgets that are children 
oj the MenuBar, and an XmRowColumn widget configured as a Pulldown 
MenuPane. In addition, it can contain a combination of XmLabel widgets, 
XmPushButton widgets or gadgets, XmToggleButton widgets or gadgets, and 
XmSeparator widgets or gadgets. 


e An Option menu system typically consists of an XmLabel gadget describing the types 
of options available, an XmRowColumn widget (configured as a Pulldown MenuPane 
widget and containing XmPushButton widgets or gadgets that represent the available 
options), and a selection area consisting of an XmCascadeButtonGadget gadget that 
contains a label string reflecting the most recent option chosen. 


2. Include the appropriate XmCreate 7ypeMenu convenience creation subroutine in the 
client application source code. For example, the XmCreatePopupMenu convenience 
creation subroutine creates an XmRowColumn widget (configured as a Popup 
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MenuPane widget) and a parent MenuShell, and returns the widget ID for the 
MenuPane widget. 


Note: You might find it useful to create a menu system without using the 
XmCreate TypeMenu convenience creation subroutines. For example, if a client 
application requires access to individual MenuShells, the MenuShells and 
MenuPanes can be created with the Enhanced X-Windows XtCreate 
subroutines (or the creation subroutines for MenuShells and XmRowColumn 
widgets). If the MenuShell is created for a Popup menu system, the MenuShell 
must be the parent of the Popup MenuPane. ff, on the other hand, the 
MenuShell is created for a Pulldown menu system utilizing a MenuBar, the 
MenuShell must be created as a child of the MenuBar widget. 


3. If the menu system you create requires submenus, they can be created in the following 
manner: 


a. Create the main MenuPane widget as a child of a top—level widget. 


b. Create a Pulldown MenuPane widget and an XmCascadeButtonGadget gadget as 
children of the Popup MenuPane. 


c. Use the resource XmNsubMenuld to attach the XmCascadeButtonGadget gadget 
to the MenuPane. 


d. Repeat steps a through c as necessary to create additional submenus of the 
newly-created submenu, changing widget—gadget names for each submenu. 
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AlXwindows Style Guide Overview 


AlXwindows is a graphical user interface based on the Open Software Foundation’s 
OSF/Motif user interface offering and is based on guidelines from the OS/2 Presentation 
Manager (PM) user environment. AlXwindows runs in the X-Windows environment. The 
components of the AlXwindows Environment are: AlXwindows and Enhanced X-Windows. 


The AlXwindows runtime environment consists of the OSF/Motif window manager and a 
graphical OSF/Motif-based desktop that provides an iconic view of the file system. 


The window manager works with the toolkit to manage the operation of windows on the 
screen. The window manager provides functions for moving and resizing windows, reducing 
windows to icons, restoring windows from icons, and arranging windows on the workspace. 
An additional AlXwindows window manager feature is the icon box. The icon box contains 
icons for all windows operating under the window manager. 


The AlXwindows application development environment provides a high-level toolkit based 
on OSF/Motif and consists of the following tools: the OSF/Motif user interface toolkit 
bindings, a widget library that provides user interface objects using an X window, a gadget 
library providing windowless widgets, and the Enhanced X-Windows user interface toolkit 
bindings. 


The AiXwindows toolkit is a collection of widgets and gadgets for building AlXwindows 
applications. The toolkit provides a standard graphical interface upon which the window 
manager is based. Toolkit widgets provide a 3—D reference appearance that gives users 
real-world, visual cues to the effects of their actions. 


Enhanced X—windows is a network transparent windowing system designed to enhance the 
usability of the overall application processing environment. 


User Control 
A major software design goal should be user control of an application. User control gives the 
user the tools to get the job done and the ability to control those same tools. Users are in 
control of the application when the application is designed with these principles in mind: 


e Consistency 

e User—Object Interaction 

e Flexibility 

e User response to irreversable actions. 


Because all applications differ in various ways, these principles may not always apply. 
Consistency 
Above all else, an application should be consistent. In addition to being consistent within its 


self, an application should be consistent with other applications that share the same 
environment. 
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Application consistency means the following: 


e Similar controls operate alike or almost alike and have the same or similar uses. For 
example, since pulldown, popup, and cascading menus are similar controls, their 
operation and use should be similar. 


e The same action should always have the same result. For example, click the Select 
mouse button on the Window Menu button of the window frame to display the window 
menu or click the mouse button twice (double click) to perform the default action. 


e The location of the mouse pointer should be determined by direct manipulation and not 
positioned arbitrarily by the application. 


An application should present its capabilities in an orderly manner. Necessary and 
commonly used functions are presented first and in a logical order. For example, essential 
functions could be included in a menu bar at the top of the client area where they are always 
visible and ready for selection. 


More sophisticated or less frequently used functions can be hidden from immediate view. 
For example, dialog boxes provide a mechanism for hiding settings and functions that are 
infrequently used. 


Decisions about the placement of functions are not easy to make. From the implementation 
standpoint, all functions are important. Often, however, a relatively small number of functions 
account for the majority of usage. These functions need to be prominently featured, but they 
can be prominent only if other functions are hidden. 


Consistency among applications increases the user’s sense of mastery. Experience with one 
application can be readily applied to another application, creating a positive transfer of 
knowledge. The focus of a computer session becomes the task at hand, not “learning a new 
application”. When applications work in a manner that is consistent with other applications, 
users can enjoy a feeling of immediate confidence in their ability to master the new program. 
Also, they are pleasantly surprised when trying new functions because, although new, the 
functions seem familiar. 


User—Object Interaction 
User—object interaction describes the action transfer between a user and an object. This 
interaction connects a user’s action to an observable response from an object. In this type of 
interface, the user experience the immediate visible result of an action. 


The immediate visual response is important to the success of an application. Performance 
problems caused by inefficient program design and implementation make it difficult for users 
to concentrate on the task at hand and can render an otherwise well—designed application 
unusable. 


User—object interaction simulates actual human actions where users use various tools to 
perform tasks on physical objects. Users control their AlIXwindows environments by direct 
interaction with graphical controls similar to controls they use in real life. For example, 
buttons push to start an action and the slider on a scale actually slides to select a setting. 


Another feature of user—object interaction is that the output of the application is also 
available as input. For example, a list of files is not only the result of a command, but also a 
collection of screen objects that a user can act upon. 


User—object interaction gives the users control by enabling them to manipulate objects by 
grabbing, pointing or selecting the object, rather than by typing a command on a command 
line. Giving users control through user—object interaction also means reducing, wherever 
possible, the amount of information the user must memorize. 
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Flexibility 
Flexibility should be apparent in both the operation and configuration of an application. 


Providing multiple ways for users to access application functions and accomplish their tasks 
increases their sense of control. For example, a function could be accessed through a 
pull-down menu, a mnemonic key press, or a keyboard accelerator. Giving users control 
through flexibility enables them to select the best method for accessing a function based on 
criteria they choose,for example,experience level, personal preference, unique situation, or 
simply habit. 


Allowing users to configure settings and select personal preferences enhances their sense 
of control and encourages them to take an active role in understanding the product and how 
it works. To be effective, the configurability of your application must be easily accessible. 


User Response to Irreversable Actions 
If a task has irreversible negative consequences, it should require users to make an explicit 
action before performing the task. For example, a worksheet could be saved by clicking the 
Select mouse button or typing the Select key on a Save push button. To delete the same 
worksheet should require clicking the Select mouse button or typing Select on an Erase 
push button and answering some type of a question with another selection action. For 
example, “Are you sure you want to erase this worksheet?”. 


Warnings help protect users from inadvertent destructive operations, yet allow them to 
remain in control of the application. Operations that may cause a serious or unrecoverable 
loss of work should warn users of the consequences and request explicit confirmation. 


By anticipating errors, you enable the support of recovery attempts and can provide 
messages informing users of the proper corrective action. Part of this support can be 
context-sensitive help and provisions for undoing an action. To avoid excessive errors, 
controls can be temporarily disabled when it would be inappropriate to use them. Disabled 
controls should provide a visual cue that they are not currently operable. 


Context-sensitive help aids understanding, reduces errors, and eases recovery efforts. Help 
information text should be clear, concise, and written in everyday language. Help information - 
should be readily accessible and just as readily removable. 


Many users are most comfortable with learning how to use software applications when they 
use a natural, trial-and error method. An undo function supports learning by trial-and—error 
by minimizing the cost of errors. The undo function allows users to retract previous actions, 
and helps foster a spirit of exploration and experimentation. 


The Elements of an AlXwindows Program Environment 
At the highest level, the AlXwindows program environment is composed of the following 
four elements: 


e Aninput selection model. 
e A window manager. 


e Other application programs. 


The Input Selection Model 
The AlXwindows environment is based on an object—action input selection model. The 
selection model defines the actions that users performs to control the window manager and 
applications in the AlXwindows environment. © 


The selection model follows a point-and-click paradigm. Users first point at and select an 
object with which to work, and then point at and select an action to perform on the selected 
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object. The AlXwindows selection model is discussed in Understanding Consistent Behavior 
in an AlXwindows User Application. 


Window Management 
The window manager provides users with a way to manipulate the windows displayed in 
their AlIXwindows environment. Typical manipulations include moving, resizing, enlarging, 
reducing, and arranging windows as needed. 


The AlXwindows window manager, mwm, frames application windows with an 
eight-segment border that can be stretched to resize the window. A title area, supplied by 
the window manager, displays a title for the window and can be used to move the window. 
Graphical buttons embedded in the window manager frame provide a window management 
menu and other window controls. Additionally, the AlXwindows window manager has a 
three—dimensional appearance so that the control buttons, when pressed by the mouse 
pointer, actually look like they have been pressed. The window manager helps provide for 
consistent behavior from one application to the next and is discussed in Understanding the 
AlXwindows Window Management Environment. 


Application Programs 
Application programs fill the space inside the window frame. By following the selection 
model and the guidelines in this guide, any applications you create should be consistent with 
the behavior of other applications in the AlXwindows environment. Designing applications 
with consistent behavior and the proper use of controls are discussed in Understanding 
AlXwindows Client Area Design., Understanding AlXwindows Application Graphic Controls, 
Understanding AlXwindows Menus, and Understanding AlXwindows Dialog Boxes. 


Related Information 
The following topics are discussed in this chapter: 


Understanding the AlXwindows Window Management Environment. 
Understanding Consistent Behavior in an AlXwindows User Application 
Understanding AlXwindows Client Area Design. 

Understanding AlXwindows Application Graphic Controls 
Understanding AlXwindows Menus 

Understanding AlXwindows Dialog Boxes 


Understanding International Implementation for AlXwindows Application Design 


Understanding the AlXwindows Window Management 
Environment 


The AlXwindows user interface provides an environment designed to facilitate 
communications between the user and your application. This environment is composed of 
discrete graphical elements. 


The graphical elements of the AlXwindows user interface facilitate communication by 
providing the user with a metaphor, a figurative concept suggestive of real world objects. 
Through this metaphor, interaction with your application should be more familiar (thus more 
intuitive) and less technical than the traditional user interface provided by the command-line 
prompt. This metaphor is usually referred to as a desk, desktop, workspace, or workbench. 
While desktop is perhaps the more widely known term, this guide uses the term workspace 
to emphasize that applications in the AlXwindows environment need not be office oriented 
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and that the functionality and graphical elements of the user interface are tools that allow 
users to accomplish tasks with their computers. 


The elements of the user interface, the objects that the user sees (for example, windows, 
icons, menus, and dialog boxes), appear on the workspace and can be stacked on top of 
each other like papers on a desk or tools on a workbench. 


The following major points about the graphic elements of the AlXwindows workspace are 
described: 


e Types of windows 
e Window anatomy 


e The icon box. 


Types of Windows 
In the AlXwindows environment, the user communicates with your application using 
windows. A window is an area of the screen (usually rectangular) that provides the user 
with the functional means to communicate with your application and through which your 
application can communicate with the user. 


A typical AlXwindows environment may have several applications in operation 
simultaneously. Each application typically has a main or primary window that displays data 
and in which the user has their primary interaction with the application. Additionally, 
applications usually have one or more secondary windows (dialog boxes) that carry on 
context—specific dialogues with the people using the application. 


While your application can be made up of many windows, each window will be one of only 
two basic types: 


e A primary window, or 


e Asecondary window. 


Primary Windows 
A primary window is the window by which all the other windows used by your application are 
generated. A primary window may be obscured by overlapping windows. Your application 
can have more than one primary windows. 


A primary window is the only window by which an application can be closed. That is, when 
users close the last primary window of an interactive application, the application session 
should end. Closing a primary window causes all secondary windows associated with that 
window to go away. 


When the user invokes your application, the application’s first task is usually to display a 
primary window. Because of this, the user often thinks of the primary window as the main — 
window. This provides the user with a valuable point of reference: they feel in control 
knowing there is a main window from which all else follows and to which they can return. 


You should design your application to encourage this sense of control, and so that, as the 
user opens and closes windows in their dialog with your application, they can always return 
to a primary window. A primary window should remain consistent in appearance and 
behavior with the last time they were there. 


Secondary Windows 
Context—specific dialogs usually occur inside secondary windows called dialog boxes. When 
the dialog is completed, the secondary window usually disappears. 
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Secondary windows are always related to a parent window. Sometimes the parent is a 
primary window, sometimes another secondary window. A primary window can have any 
number of secondary windows as its children. 


Secondary windows are not constrained to be inside the primary window, but they will 
always appear on top of that parent window in the window hierarchy. Think about how your 
application will distinguish between primary and secondary windows. One method is to 
include identifying information in the title area. For application—oriented programs, the 
application name is followed by the file name in the title bar; for object—oriented programs, 
the object name is followed by the function. Secondary windows then have title areas that 
include the application or object name and the implied action. 


When a primary window is minimized, its secondary windows are temporarily removed from 
the display. 


Window Anatomy 
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The AlXwindows window manager (mwm) provides windows with a window frame that 
contains various components. These components are functional, providing a convenient way 
for mouse users to invoke window management functions. Keyboard—only users use the 
window menu provided by mwm to invoke window management functions. Window frame 
components are sometimes called decorations. 


Along with window frame components, the AlXwindows window layout includes a client 
area, the area inside the window frame, for your application to use. 


In general, a window consists of the following components: 
e Window menu button 

e Window control buttons 

e Title area 

e Resize border 


e Client area. 
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The components of the standard window layoutmay require some amount of modification for 
specific implementations. For example, it is inappropriate to resize some windows. These 
should have their resize borders removed. 


Window Menu and Window Menu Button 
The window menu button is located in the title bar, on the left side of the title area, and is 
used to display the window menu. Double—clicking the Select mouse button with the mouse 
pointer over the window menu button closes the window. The window menu provides a 
standard location for important window management functions. Users can browse the menu 
to see what actions are available. The window menu pulls down from the upper left corner of 
the window frame. Mouse users display the window menu by pressing the Select mouse 
button with the mouse pointer on the window menu button. Keyboard users display the 
window menu by pressing the Shift+Esc keys when the input focus is in the window. 


The window menu and window menu button are sometimes called the system menu and 
system menu button respectively. 
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Restore Alt + F5_ 












Size 


Alt + F8 
Minimize Alt + F9 
Maximize Alt + F10 
Lower Alt + F3 


Alt + Fa 


The standard selections of the window menu are shown in the figure. In the figure, the Move 
selection is being chosen. Also, the Restore function is not highlighted to provide a visual 
cue that, in the present context, the function is unavailable. The selections of the window 
menu have the following functions and accelerators: 


Restore Alt+F5 Restores a minimized or maximized window to its normal 
size. This selection is de-emphasized (grayed out) when 
the window is in its normal state. 

Alt+F7 Moves | Moves a window around onthe workspace. == window around on the | Moves a window around onthe workspace. == 

Alt+F8 ‘| Stretches or shrinks a window in the direction indicated 
by the mouse pointer. 
}Minimize | AltsFQ | |Changesawindowintoanicon. = = = = = a window into an icon. 


oe ee 
(Optional) Moves a window to the back of the workspace 
(the bottom of the window stack). 


Keyboard accelerators for the window menu are optional. If you decide to use accelerators, 
use the accelerators suggested above. 













Window Control! Buttons 


Window control buttons are push buttons located in the upper right corner of the 
AlXwindows window frame. They provide a short-cut for invoking window management 
functions without pulling down the window menu. Users invoke window management 
functions by clicking on the appropriate window control button. 

Minimize 


OS  Hivindows To] 
| 


The functions chosen for window control buttons are implementation—dependent and include 
such functions as Maximize and Minimize. 


Maximize 
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Minimize Button 


The minimize button is located to the immediate right of the title area. It provides the same 
function as the Minimize selection in the window menu. Users click the Select mouse button 
with the mouse pointer on the minimize button to shrink a window to an icon. 


Maximize Button 


The maximize button is located between the minimize button and the resize border. It 
provides the same function as the Maximize selection in the window menu. Users click the 
Select mouse button on the maximize button to enlarge a window to its maximum size. The 
maximize size of a window is established by the application. Clicking the Select mouse 
button with the mouse pointer on the maximize button of a maximized window restores the 
window to its original size, the same function as the Restore selection of the window menu. 


Title Area 
The title area is the horizontal bar that lies between the window menu button and the 
window control buttons, and, as part of the window frame, highlights when the window has 
the input focus. The title in the title area identifies the window. | 


Pressing the Select mouse button with the mouse pointer on the title area and dragging the 
mouse pointer on the screen will move the window to a new location. Clicking the Select 
mouse button with the mouse pointer on a title area (or frame) raises that window to the top 
of the window stack. 


The window manager displays an application title in the title area. The application title is 
supplied by the application and clearly identifies the window and its role within your 
application. 


You provide the window manager with a title. In object oriented environments, this title 
should be the name of the object followed by the application name; in file-based 
environments, the title could be the name of the application followed by the file name. 
Multiple windows of the same application should have titles that identify them with the 
application in some way, but can otherwise be distinct from one another. 


The title area should not display the version number of your application. Nor should you use 
it to display system messages. Use the title area for information that stays relatively constant 
throughout the work session of your application. 


Resize Border 
Your application suggests the initial size of its windows to the window manager. Window 
sizes vary according to the work users perform in them. At any time, users should be able to 
alter the size of a primary window. | 


The window manager provides a functional window frame which surrounds the client area. 
The window frame highlights when input focus is passed to the window. Resizable windows 
have a wide frame border that users can drag when they want to change the window’s size. 


Client Area 
The client area is the portion of the window in which users perform most application—level 
tasks. For example, if users are working with a graphics editor or a text editor, the client area 
contains the figure or document being edited. The client area is inside the window frame and 
can be composed of multiple work areas. 


The Icon Box 
By default, minimized windows (icons) are placed on the workspace in a row beginning at 
the lower left corner of the screen. However, under the management of the window 
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manager, users can choose to group minimized windows in an icon box. They can also 
choose to have minimized windows placed at the location the normal window occupied. 


An icon box acts like a typical window in the sense that it has a window frame and frame 
controls. Like other windows it can be sized, moved, minimized, maximized, restored, and 
lowered. However, an icon box cannot be closed. 


Understanding Consistent Behavior in an AlXwindows User 
Application 


The AlXwindows environment provides users with a behaviorally consistent graphical user 
interface based on a number of discrete but related operational models. Using these models, 
much of the interaction with an application program can be reduced to the following 
scenario: users select an object using the input device with which they feel most 
comfortable; they then select an action to perform on the selected object. 


Consistent behavior enables the user to perform a task by focusing on the task itself rather 
than on the tools or the method in which they perform the task. Just as an automobile is a 
tool for transportation that does not require the average person to be a mechanic, a 
user-oriented software application provides users with a productivity-enhancing tool without 
requiring them to become engineers. 


An understanding and consistent use of the following four operational models will help 
enable consistent behavior of your applications. 


The input focus model. 


The input device model. 


The navigation model 


The object-action selection model. 


The Input Focus Model 
A typical AlXwindows workspace can contain many windows. Like sheets of paper stacked 
on a desk, windows can be stacked on the workspace. Some windows may be partially or 
completely obscured by other windows. At any given time, however, only one window has 
the input focus. The window with the input focus is known as the active window and is the 
window where keyboard input will appear. The active window is also the only window that 
has the location cursor. Input focus can be moved from window to window. 


When a window receives the input focus, the default behavior moves the window 
automatically to the front of the workspace so that no part of the window is obscured. This 
behavior can be modified to suit the needs or preferences of the users of your application. 
Additionally, the window with the input focus has a highlighted frame, supplied by the mwm 
window manager. This highlighted frame provides a visual cue that the window is active and 
further distinguishes the active window from inactive windows in the workspace. 


The input focus model can use either an explicit or an implicit policy for moving the input 
focus from one window to another. Explicit focus is the default. 


Explicit Focus 
In explicit focus (the default), users explicitly select which window receives the input focus. 
With a mouse or other pointing device, users move the mouse pointer into a window and 
press the Select mouse button to move the input focus to that window. With a keyboard, 
users press the Alt+Esc keys to move the input focus sequentially through the windows 
stacked in the workspace. Explicit focus is sometimes known as click—to—type. 


—. 
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Implicit Focus 
In implicit focus, the input focus moves to the window into which users move the mouse 
pointer. No explicit selection action is performed. The focus policy that a user chooses to 
implement is a matter of personal preference and need. Some mouse users find implicit 
focus more convenient. When using only keyboards, there is no distinction between explicit 
and implicit focus. Implicit focus is sometimes referred to as pointer, track pointer, track 
listener, or as being real estate driven. 


The Input Device Model 
The AlXwindows user interface enables users to communicate with your application using a 
keyboard and, optionally, a mouse or other pointing device. 


Dual Access via Mouse and Keyboard 
Some users prefer controlling software programs by pointing and clicking a mouse. Other 
users dislike removing one hand from the keyboard to “catch” a mouse and prefer instead to 
control programs solely from the keyboard. Other users lack the room for a pointing device 
on their desk. Still others prefer to mix mouse usage with keyboard usage: for frequently 
performed functions, they use keyboard accelerators; for other functions, they point and click 
with the mouse. 


In AlXwindows applications, the keyboard is virtually interchangeable with the mouse. This 
enables users to pick the appropriate tool for the job or to choose the tool with which they 
feel the most comfortable. 


You should design your application so that users can control it using a pointing device, the 
keyboard, or both. Although you may decide to make the pointing device the primary means 
of control, you should not constrain users from using the keyboard for application control. 


Designing your application for dual accessibility gives users control by enabling them to 
choose the input device they find best suited to their needs, given their particular work 
situation and personal preferences. 


Keyboard Conventions | 
The keyboard conventions outlined in this section work with ANSI keyboards. Keyboards, 
however, can differ greatly among manufacturers, and even among models made by the 
same manufacturer. Therefore, exact key labels as described here may differ from those that 
you are used to seeing. For example, the Alt key is sometimes labeled Meta, Extend or 
Extend char. 


In general, all keyboards have the following types of keys: 


Alphabetic keys 
Keys representing the letters of the alphabet, the marks of punctuation, and 
text formatting functions such as the Tab, Return and spacebar keys. 


Numeric keys Keys that represent the numbers from 0 to 9. These are included near the 
top of the keyboard or, in a numeric keypad on one side. 


Navigation keys 
Keys that are pressed to move the insertion cursor. These keys are 
commonly called the arrow keys and include the up arrow, the down arrow, 
the right arrow and the left arrow. On some keyboards they are separate 
keys, on others they are included as part of the numeric keypad. Also 
included in this category are the Home, End, PageUp, and PageDown keys. 


Modifier keys Keys that are used in conjunction with other keys to modify the meaning or 
effect of those keys. The modifier keys include the Ctrl, Shift, and Alt keys. If 
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your application designates a particular key as a modifier key, that key 
should not have any other function associated with it. 


Special—purpose keys 
Keys that have particular functions and frequently have labels stating their 
purpose. Among these keys are Help, Menu, Esc, Select, Enter, Delete, 
Backspace, and Insert. 


Function keys Keys that most keyboards provide for extra or general functions. Usually 
these keys are labeled F1, F2, and the like. Some keyboards have ten 
function keys, others twelve or more. The AlXwindows environment 
assumes a keyboard with at least ten function keys. Function keys are 
usually placed either across the top of the keyboard or on one side, often 
the left. 


As noted, keyboards differ greatly and some may not have all of the keys just mentioned. 
The table lists some common substitutions. 






Description 


[Key [bescrpton «i Subtitution 
[Select | Make a selection rom the keyboard _|Spacebar or Ener | 
[Menu [invokes apopupmenu dA 
[At_______| Modes the meaning of anotherkey [wend 
[Esc —‘[Oancelscurentacion dA 
[Enter _____|lnvokesihe defauacion—————=Rewmn 


Next Field Moves location cursor to next field Tab or Ctrl+Tab 


Previous Field Moves location cursor to previous field Shift+Tab or 
Ctri+Shift+ Tab 


Also, some keyboards may have duplicate sets of keys. Numeric keys, for example, are 
often found both in the top row of alphabetic keys and in a numeric keypad and function keys 
are sometimes found both at the top of the keyboard and as a separate keypad on one side. 
These duplicate keys may have different keycodes associated with them. In such a case, 
you can design your application to provide some special functionality on the extra keys. For 
example, you might retain the top row of alphabetic keys as numeric keys and use the 
numeric keypad for special functions. 





Cursor Shapes 
While ine traditional use of a keyboard has been for text entry, the keyboard has also been 
adapted for use as a pointing device. Because of this, the keyboard has two cursors, one for 
location, the other for text insertion. 


The location cursor reflects movement on the screen using the keyboard’s cursor 
navigation keys and indicates the current location of the keyboard input focus. The position 
of the location cursor gives users a visual cue to which object they are about to select. The 
location cursor is displayed whether or not a mouse is attached and is in addition to the 
mouse pointer. For example, the location cursor can indicate which item in a list box a user 
wants to select. The location cursor is often shown as a rectangle around a control. The 
location cursor is sometimes called the selection cursor. 
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Location Cursor 


Insertion Cursor 


The insertion cursor is used in edit controls such a text entry box. It indicates the point in 
text or graphics where new characters will be inserted. In text entry, the insertion cursor’s 
default shape is a pipe (|) or bar for inserting, and a block character cell or underscore (_) for 
overstriking. In graphics entry, the insertion cursor’s shape might be a pencil, paintbrush, or 
some other graphically descriptive image. 


Inactive 





The insertion cursor is only displayed where graphics or text entry is allowed. The insertion 
cursor should change size to match the size of the current font. 


Pointing Devices 


Direct manipulation allows users to control an application by choosing selections from a 
menu and by setting controls following a point-and-click method. In the point-and-click 
method, users move the mouse until the mouse pointer is over (points to) the desired object. 
They then click the Select mouse button. 


Direct manipulation usually requires a pointing device: a mouse, graphics tablet, track ball, 
joystick, or some other such device. Typically, keyboards with two sets of arrow keys use 
one set for mouse pointer navigation and the other set for location cursor navigation. Using 
the pointing device, users can navigate rapidly around the screen and can point at and 
choose objects to work on and actions to perform. 


Throughout this guide we use the term mouse to refer to all pointing devices. You can use 
any pointing device in place of a mouse. 
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Mouse Buttons 


The Pointer 





You can use mouse buttons in combination with the mouse pointer to make selections, move 
the input focus, or position the insertion cursor. 


This guide assumes a three-button mouse and gives the following names and functions to 
mouse buttons. 






Nae [Bese 
/Select Used for selection. 





Used for direct manipulation of objects. 


Custom Used to display pop up menus and otherwise as needed for 
application—specific functionality. 
Note: The position of mouse buttons can vary depending on whether the mouse is 
configured for left— or right-handed operation. 


[Button | 
sone 


You can perform the following mouse button operations: 


Pressing Holding down a mouse button. 

Releasing Releasing a mouse button after it has been pressed. 

Clicking Quickly pressing and releasing a mouse button without moving the 
mouse. 

Dragging Moving the mouse while a mouse button is pressed. 


Double—Clicking Clicking a mouse button twice in rapid succession without moving the 
mouse pointer. 


The mouse is associated with one and only one mouse pointer. The mouse pointer 
appears on the workspace and represents the location of the mouse. Movements of the 
mouse pointer correspond to movements of the mouse. The mouse pointer is not confined to 
any specific application. Users can move it anywhere on the workspace. The mouse pointer 
is sometimes known simply as the pointer. 


Your application should only interpret the mouse pointer position; it should not attempt to 
change it. To do so would violate users’ trust in the consistency of your program and their 
sense of control. Also, changing the mouse pointer location may create problems in 
applications that use absolute location devices (like graphics tablets). 


Pointer Shapes 


The shape of the mouse pointer provides users with an important visual cue indicating the 
functionality of the area in which the mouse pointer is currently located. The figure illustrates 
the standard mouse pointer shapes. While you should not create new mouse pointer shapes 
for functions that already have mouse pointer shapes associated with them, you can create 
new mouse pointer shapes for functions not already associated with a pointer shape. Also, 
do not use a predefined shape to symbolize a function it was not designed to represent. 
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If you decide to use other mouse pointer shapes in your applications, avoid shapes that are 
hard to see, hard to comprehend, create visual clutter, or flicker excessively when changing 
shape repeatedly. 





Ensure that any mouse pointer you create has an obvious hot spot (active point). This is the 
area of the pointer image that marks the location of the mouse pointer. This is particularly 
critical for mouse pointer shapes that point to objects or specify positions. Users should be 
able to intuitively locate the hot spot (for example, the tip of an arrow or the center of a 
crosshair). 


Design your application so that users can set the ratio of mouse pointer speed to mouse 
speed. This ratio is called the gain. Mouse pointer speed can be constant or accelerating. 
The gain is typically set globally in the AlXwindows environment. Therefore, if your 
application needs to adjust the gain, implement a zoom feature rather than change the gain. 
A zoom feature (similar to the zoom lens of a camera) adjusts the gain by varying the 
magnification of the application. 


The Navigation Model 
Regardless of whether they use a mouse, a keyboard, or both, users will need to move the 
mouse pointer and the location cursor to new positions. That is, they will need to navigate 
around the workspace. 


The mouse pointer is a graphical representation of the current location of the mouse. The 
only way to move the mouse pointer is to physically move the mouse. 


The location cursor shows the current location of the keyboard focus. A user can control the 
location cursor with either the mouse or the keyboard. 


The Object—Action Selection Model 
In object—action selection, users first select an object, and then select an action to perform 
on that object. Object—action is patterned after real life and provides users with a readily 
comprehensible operational model for AlXwindows applications. 


It is helpful to note that the term object includes not only recognizable objects like windows 
and push buttons, but also objects such as the individual letters of a text file, that are 
perhaps less often thought of as discrete entities. 
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The AlXwindows selection model employs the following kinds of selection: 

e The selection of a single object. 

e The selection of a range of objects. 

e The selection of additional (non—contiguous) objects, including multiple ranges. 


To make selections in AlXwindows applications, users always use the same basic steps. 
First, they place the pointer (mouse) or location cursor (keyboard) on the object they wish to 
select. Second, they perform a specific selection action. Thus the kinds of selection listed 
here and explained below are not separate types of selection. Rather, they are variations of 
the one selection model theme. Which variation they use depends on whether they wish to 
select a single object, a range of objects, or several additional (non-contiguous) objects. 


Some controls, as selection objects, make specific assumptions about the selection model. 
For example, a set of radio buttons assumes that each button’s selection is mutually 
exclusive. Thus, while radio buttons follow the selection model for single objects, they do not 
allow any other type of selection. Check buttons, on the other hand, assume that each 
button’s selection is not mutually exclusive. While they also follow the selection model for 
single objects, they allow the selection of multiple buttons without deselecting the prior 
selection (as is the case in strict single selection). Check buttons are an example of what is 
called multiple selection. 


The following table lists the mouse button and keyboard operations of the AlXwindows 
selection model. 


Selection Task Keyboard Selection 
Operation 


Select a single object (set the anchor Click Press the Select key 
point) and deselect all other objects. Select 


Select a range of objects (set the anchor | Drag Select | Press the Shift+navigation 





point at range beginning) and deselect all keys 
other objects. 
Toggle the selection of all objects Shift+click Press the Shift+Select keys 
between current location and the anchor | Select 
point. 
Toggle the selection of an additional Ctrl+click Press the Ctrl+selection 
object. selection cperation keys 
operation 


Single Selection Selects One Object Only 
Single selection is probably the most common type of selection. In single selection, users 
select a single object upon which to perform an action. 


In single selection, users move the mouse pointer or location cursor to a selectable object 
and then make their selection. Selecting an object changes the object’s appearance. This 
provides users with the necessary visual cue to reinforce their sense of control over the 
selection process. For example, as shown in the figure, the insertion cursor in a text entry 
box is emphasized when the box is selected and de-emphasized when the box is not 
selected. In single selection, when one object is selected, other objects previously selected 
are deselected. 
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You can use single selection for such actions as selecting the active window (when the input 
focus policy is explicit selection) or selecting a push button or other type of control. In a text 
entry area, they use single selection to position the insertion cursor. 


Join Style 


Miter 


Round 


Bevel 





Single Selection with a Mouse 

Users working with a mouse perform the following steps to select a single object: 
1. Move the mouse pointer until it lies over the object they wish to select. 

2. Click the Select mouse button to select the object. 


Pressing the Select mouse button changes the object’s appearance providing the visual cue 
to which object is about to be selected. Releasing the button selects the object and 
completes the single selection process. 


Single Selection with a Keyboard 
Keyboard users perform the following steps to select a single object: 


1. Move the location cursor using the cursor navigation keys until it lies over the object they 
wish to select. 


2. Press the Select key. 


Pressing the Select key has the same effect as a mouse user’s pressing the Select mouse 
button; it changes the object’s appearance and provides the visual cue that the object is 
about to be selected. Releasing the Select key, selects the object and completes the single 
selection process. 


Range Selection Selects Contiguous Objects 
In range selection, users select a range of contiguous objects upon which to perform some 
action. The range is based on, but not limited to, a rectangular area. To be included in the 
range, objects must be completely included in the selection action. 


In range selection, users move the mouse pointer or location cursor to the selectable 
graphics object and then make their selection. The object’s appearance changes to provide 
a visual cue, just as it does in single selection. 


In range selection, as the next object in the range is selected, the previous object in the 
range remains selected. Both objects become part of the range being selected. Any number 
of objects can be selected in range selection as long as they form a contiguous group. 
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Dear Maureen, 


Thanks for sending me the new shell script. It should make 
it much easier for me to rename all of the new files. 


I’m sending you a script that you may also find useful. Let 
me know whatlwhat yoo you think of it. 





You can use range selection during cut-and-paste operations on text. As illustrated, words 
are selected as a range of ASCII characters and then acted upon (cut or pasted). 

Range Selection Using a Mouse 

Mouse users for range selection perform the following steps: 

1. Position the mouse pointer over the object that starts the range. 

2. Press the Select mouse button. 

3. Drag the mouse pointer to the object that ends the range. 

4. Release the Select mouse button to complete the range selection. 


For example, to select four contiguous items from a list box, users position the mouse 
pointer on the first item, press the Select mouse button, drag the mouse pointer to the fourth 
item, then release the Select button. The appearance of each selected item changes as it is 
selected, providing a visual cue. Releasing the Select mouse button completes the range 
selection. 


An alternative to dragging the mouse pointer from the start to the end of the range is to click 
the Select mouse button on the start, move the mouse pointer to the end of the range, and 
press the Shift+Select keys to complete the range selection. 
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Range Selection Using a Keyboard 
Keyboard users for range selection perform the following steps: 


1. Position the location cursor (insertion cursor for editable areas) using the navigation keys 
so that it is over the object that starts the range. 


2. Hold down the Shift key and press the navigation keys to drag the cursor to the object 
that ends the range. 


3. Release the Shift key to complete the range selection. 


As with range selection using the mouse, each object’s appearance changes providing the 
visual cue of selection. When the Shift key is released, the selection is complete. 


For example, to select five contiguous items from a list box, users position the location 
cursor on the first item, press the Shift key, press the navigation keys to drag the location 
cursor to the fifth line, then release the Shift key. 


Alternatively, press the Select key to start the selection, press the navigation keys to move 
the location cursor to the end of the range, and then press the Shift+Select keys to complete 
the range selection. 


Selecting Additional Non—contiguous Objects 
Users can make one or more additional selections, forming a non—contiguous group of 
objects. 


To begin an additional selection, users select a first object using single selection or a first 
range of objects using range selection. Other objects can be added to the selection group by 
repositioning the mouse or location cursor, and selecting the objects. 


Like single and range selection, objects or ranges that are part of a non—contiguous 
selection provide a visual cue that they are part of the selection. 
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Users find the selection of additional non—contiguous objects, especially the selection of 
non-contiguous ranges, useful in text processing. Note also that the operation that performs 
a selection of additional non—contiguous objects works as a toggle. That is, if the object is 
not selected, the operation selects it; if the object is selected, the operation deselects it. 


Making Additional Non—contiguous Selection Using the Mouse 
Mouse users make an additional selection perform the following steps: 


1. Select the first single object or range using the methods described in the preceding 
sections. 


2. Position the mouse pointer on the next object they wish to select. 


3. Press the Ctrl key and the Select mouse button to mark the next object or next range in 
the non—contiguous selection. 


4. (For range selection only) Drag the mouse pointer to the end of the range, then release 
the Ctrl key and the Select mouse button. 


5. Repeat steps 2—4 for each additional object or range in the non-contiguous selection. 


For example, to select several non—contiguous items from a list box, users position the 
mouse pointer on the first item, click the Select mouse button to select it, move the mouse 
pointer to the next item for selection, press the Ctrl key and click the Select mouse button to 
select that item. The appearance of the selected list items changes as the item is selected, 
providing a visual cue to the selection. 


An alternative to the press—drag—release operation is to press the Ctrl key and click the 
Select mouse button to begin the selection, reposition the mouse pointer at the end off the 
selection, then press the Shift key and click the Select mouse button. This alternate method 
for selecting multiple ranges is similar to the alternative method for selecting a single range 
described above. 
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Making an Additional Non-contiguous Selection Using the Keyboard 
Keyboard users make additional (non-contiguous) selections perform the following steps: 


1. Select the first single object or range using the methods described in the preceding 
sections. 


2. Position the location cursor on the next object they wish to select. 


3. Press the Cirl+Select keys to mark the next object or start of the next range in the 
non-contiguous selection. 


4. (For range selection only) Press the Shift key and press the navigation keys to drag the 
location cursor to the end of the range. Release the Shift key to mark the end of the 
range. 


5. Repeat steps 2—4 for each additional object or range in the non—contiguous selection. 


For the same example as above, to select several noncontiguous items from a list box, 
users position the location cursor on the first item, press the Select key to select it, move the 
location cursor to the next item for selection, press the Ctrl key and press the Select key to 
select that item. As with mouse selection, the appearance of the selected list items changes 
as the item is selected, providing a visual cue to the selection. 


Alternatively, press Ctrl+Select keys to start the range, move the location cursor using the 
navigation keys to the end of the range, and then press Shift+Select keys to complete the 
range selection. 


Deselecting an Object 
A selection operation can be undone (canceled) by typing the Esc key before the operation 
is completed. Once completed, an entire previous selection can be deselected by making a 
single—object selection. 


A previously selected object can also be deselected by toggling its selection state. Usually 
this requires positioning the mouse pointer or location cursor on the object and then pressing 
the Ctrl key and the Select mouse button (for mouse users) or by typing the Ctri key and the 
Select key (for keyboard users). This deselection method is commonly used to deselect one 
object in a range of selected objects without deselecting the rest of the range. 


A previously selected range of objects can be deselected by pressing the Ctrl key and using 
a drag operation to toggle their selection state. 


Selecting the Default Action | 
Some objects have default actions associated with them. For example, An icons’ default 
action is restoring itself to a normal window. 


For mouse users, double-clicking the mouse with the mouse pointer over an object selects 
the default operation for that object. For example, double-clicking the Select mouse button 
with the mouse pointer over an icon restores the icon. Double—clicking the Select mouse 
button with the mouse pointer over the window menu button closes the window. 
Double-clicking the Select mouse button with the mouse pointer in a dialog box performs 
the default action associated with that dialog box. 


For keyboard users, typing the Enter key with the location cursor over an object selects the 
default operation for that object. For example, typing the Enter key with the location cursor 
over an icon, normalizes the icon. Typing the Enter key with the location cursor in a dialog 
box performs the default action associated with that dialog box. 
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Auto Selection 
Auto selection combines the act of moving the location cursor with the act of selecting the 
object. In the selection model presented in this chapter, users move the location cursor to an 
object and then explicitly select the object by pressing the Select mouse button or the Select 
key. When auto-selection is employed, users simply move the location cursor to an object 
and the object is selected; no explicit selection action is required. 


Understanding AlXwindows Client Area Design 


The AlXwindows window manager is responsible for providing window management 
services for the windows of all applications in the AlXwindows environment. Your application 
is responsible for organizing the client area of the main window, any subareas, and any 
secondary windows. 


Organizing client areas is an important part of your design process. Depending on the nature 
of your application, you may choose to divide the client area into one or more subareas. 
Additionally, you may choose to design your application with secondary windows (dialog 
boxes). subareas and secondary windows visually reinforce the organization of your 
application and increase the user’s sense of control over its operation. 


e Client Subareas 

e Grouping similar controls. 

e Presenting multiple controls. 

e Laying out AlXwindows application client areas. 


Other articles discuss the use of controls, menus, dialog boxes, and help in more detail. 


Client Subareas 
As mentioned, you can divide the client area of your application window into one or more 
subareas. Client subareas are very application specific, with the possible exception of the 
menu bar. 


Menu Bar 
The menu bar is the horizontal bar that appears just below the title area. It contains a list of 
menu topics from which users can select. A single letter mnemonic for each menu topic is 
underlined. 


Keyboard users select a topic by pressing the F10 key to move the location cursor to the 
menu bar and then typing the mnemonic letter of the topic. Mouse users select a topic by 
positioning the mouse pointer over that topic and selecting it with the Select mouse button. 
Selecting a topic causes a pulldown menu to display selectable items related to that topic. 


Note that commands are not included as topics in the menu bar because they would prohibit 
users from browsing the menu topics. 


Because menus are a principal method of interaction between users and AlXwindows 
applications, most applications require a menu bar. Refer to AlXwindows Menus Overview 
for more detailed information about menus. 
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Control Panels 
Some applications benefit by organizing part of the client area into a subarea called a 
control panel. A control panel is a group of like controls having similar functions. Control 
panels can either be part of the client area, if their use is required frequently, or part of a 
dialog box, if their use is required occasionally. Control panels are made up of the controls 
discussed in Understanding AlXwindows Application Graphic Controls. 


Message Area 
You may decide that it is more efficient for the user to view messages, but not warnings or 
messages requiring immediate action, within a subarea of the client area rather than ina 
separate message box. If so, the messages should appear at the bottom of the client area 
so that messages are not obscured by pulldown menus. The message can be either in a line 
reserved for messages or in a line temporarily used for the message and then returned to its 
previous use. Warnings and messages that require immediate action are not displayed this 
way. Rather, these are always displayed in message boxes to give them greater visibility in 
the workspace. 


Command Line 
Although the AlXwindows environment provides a graphics oriented, object—action selection 


model, your particular application may permit the use of typed commands to enhance the 
control users have over your application. 
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Command lines should generally run from border—to—border across the bottom of the client 
area, just below the message area, or directly below the menu bar at the top of the client 
area. . 


Client Controls 
Each subarea can contain a variety of controls enabling the user to manage that subareas. 
Like subareas, the controls chosen for a particular sub—area, are very application specific. 


The controls you choose depend on the needs of the people who will use your application, 
and your application design. 


Window Panes 
Depending on the needs of your application and the people who use it, you may decide that 
it is better to divide your client area into window panes rather than into fixed partition 
subareas. 


Panes can be either vertical (one on top of the other) or horizontal (side by side). The user 
can resize panes by dragging the boundary between the panes. Making one pane bigger 
makes the other pane smailer, while the overall size of the window remains the same. 


Scroll bars 
People use scroll bars to scan rapidly through the contents of a window. The current location 
of the scroll bar is shown by the position of the slider in the scroll bar area. 


Resizable windows and window panes require scroll bars if the information in them will 


require more space or become obscured by the border of the subareas. The following figure 
shows vertical and horizontal scrollbars. 


XmNaccelerators 
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XmNborderPixmap 
XmNborderWidth 
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XmNmappedWhenManaged 
XmNscreen 





Scroll bars are located to the right (vertical) or on the bottom (horizontal) of the area to be 
scrolled. Scroll bars can also be used in dialog boxes or in combination with other controls. 
Their operation is discussed in Understanding AlXwindows Application Graphic Controls. 
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Other Controls 


The AlXwindows object—action selection model uses a number of other controls. These 
controls are graphical representations of real life controls and include the following: 


Push buttons 
Radio buttons 
Check buttons 
List boxes 
Entry boxes 
Scales 

Scroll bars. 


Other Client Areas 


Menus 


In addition to organizing your application’s client area into subareas, you may choose to 
organize your application and its operation using some of the other methods provided by the 
AiXwindows environment. These include pop—up menus, cascading menus, and dialog 
boxes (secondary windows). Like subareas, these other areas visually reinforce the 
organization of your application and increase the user’s sense of control over its operation. 


AlXwindows menus work just like real life menus. Menus enable users to choose from a list 
of possible selections. Besides the pulldown menus on the menu bar, the AlXwindows 
environment has the following types of menus: 


Pop-ups Menus that pop up from nowhere rather than being related to a menu bar. 


Cascading Menus that cascade to the right and down from either pulldown or pop—up 
menus and provide a subsidiary level of selection. 


Option Menus that display from a dialog box. Those usually appear when a push 
button is pressed. 


Dialog Boxes 


Controls that are not frequently in use during the operation of your application can be 
included in a dialog box. A dialog box is a separate window from the application’s main 
window, and contains controls that should be readily accessible but that do not need to be 
displayed permanently in the client area. 


Grouping Similar Controls 


Some controls perform similar functions or are logically related. For ease of use, as well as 
for proper visual design, these controls should be grouped into sets. This keeps the user 
interface of your application organized. Similar or related controls can be placed either in 
group boxes or in window subareas. Typically, group boxes occur in dialog boxes and are 
often surrounded by a simple frame. Window subareas often appear as part of an 
application’s main window, and contain frequently—used controls that must remain readily 
available. 
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Grouped controls provide a visual cue that the controls are related to one another by 
isolating them from other controls. A group box or control panel usually has a title printed 
near it. Controls can be grouped in one row or column, or in multiple rows or columns. 


Designing Grouped Controls with Push Buttons 


Grouped controls containing push buttons should adhere to the following guidelines: 
e Use push buttons sparingly 
e Use push buttons only for frequently-used commands. 


Unless you are trying to duplicate the physical appearance of an existing piece of 
equipment, place push buttons in dialog boxes in a row along the bottom of the box or ina 
column along the right side of the box. 


Combining Controls 


The AlXwindows environment does not restrict the combination of controls only to these 
combinations mentioned in this guide. The criteria for developing control combinations 
should always be consistent: will this combination, give control to the people who use it to 
work more efficiently and, as a result, become more productive. 


Presenting Multiple Controls 


The AlXwindows environment uses four basic ways of displaying multiple controls: 
e Pull—-down menus 

e Pop—up menus 

e Dialog boxes 


e Control panels. 
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Pull-Down Menus 
Pull-down menus usually contain push buttons, radio buttons, or check buttons as selection 
items. Selections can lead to dialog boxes or other controls. Menu items are always 
presented in a vertical column. To display a pulldown menu requires some degree of mouse 
movement or the use of an Alt key + mnemonic accelerator. While the selections of a 
pulldown menu do not appear until the menu is selected, the title of a pulldown menu is 
always displayed in the menu bar. pulldown menus combine a visual cue of their presence 
with an efficient use of space. 


Pop—Up Menus 
Pop—up menus, like pulldown menus, usually contain push buttons, radio buttons, or check 
buttons, and can have selections that lead to dialog boxes or other controls. Also like 
pulldown menus, pop—up menus are always presented as a vertical column. Pop—up menus 
are associated with a particular area of the screen. The advantage of pop—up menus is that 
they require no mouse travel; they simply pop-up at the current mouse location (provided 
that location has a menu associated with it). While pop-up menus take up no Screen space 
until they are displayed, they provide no visual cue to their existence. 


Dialog Boxes 
Dialog boxes can contain all the button, box, and valuator controls. Usually, when the dialog 
box is displayed, all necessary controls are present. However, your application may require 
some extra display operations that should be in the dialog box but need not be displayed all 
the time. If so, you can include an option menu push button in your dialog box. 


Dialog boxes allow a lot of flexibility in the arrangement of controls. Controls can be grouped 
in boxes, organized in rows or columns, and separated by white space for better visibility. 


Message boxes are usually displayed by the application without any explicit action. Dialog 
boxes, on the other hand, are usually displayed as a result of some explicit action. Dialog 
boxes can be displayed directly using a keyboard accelerator. This saves the time and extra 
steps required when selecting them from a menu. Like pop—up menus, dialog boxes use 
space efficiently because they are not visible until displayed, however, this means they do 
not provide a visual cue to their existence. Dialog boxes are removed from the workspace 
when their primary window is minimized. Dialog boxes are returned to the workspace when 
their primary window is restored. 


Control Panels | 
Control panels, like dialog boxes, can contain all the button, box, and valuator controls. They 
also offer the same flexibility of arrangement. Control panels, since they are permanently 
displayed, offer the potential of having frequently used controls always available. Being 
displayed, they offer a strong visual cue to their existence, but they do take up screen space. 


Laying Out AlXwindows Application Client Area 
The nature of your application may be such that you will need to design control panels or 
dialog boxes specific to your situation. When doing so, it is important for the 
AlXwindows-—conformity of your application to use the following criteria: 


e Arrange controls in natural scanning order 

e Arrange controls in the sequence people use them 
e Allow users to adjust the client area 

e Choose the appropriate control for the job 


e Know when to use a pop—up menu and push buttons 
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e Know when to use dialog boxes and menus 
e Align columns of controls 


e Use defaults consistently and for common settings 


Arrange Controls in Natural Scanning Order 
Design the layout of your application windows according to the natural scanning order of the 
people who will be using your application. In most cases, this order will be from left to right 
and from top to bottom. 


Arrange Controls in the Sequence People Use Them 
Intimately connected to the use of natural scanning order in control layout is the 
arrangement of controls in the sequence in which people will use them. The natural 
scanning order gives the position; the sequence of use gives the priority. 


For example, suppose you have a dialog box that has push buttons that accept changes, 
test them, restore original values, and cancel the dialog box without making changes. 
Western conventions dictate that the push buttons be displayed from left to right. The 
sequence of use suggests that the OK button should be on the left (as the most frequently 
used button), followed by Apply, Reset, and Cancel. 


Adjusting the Client Area 
To increase the control users have over your application, your application should allow users 
to adjust the client area to fit their needs. 


If your application uses window panes, it should allow users to adjust the size of the panes 
to suit their needs by repositioning the sash, the border separating the two panes. When 
one pane increases in size, the other pane decreases by the same amount. The overall 
sizes of the window frame and the client area do not change as the panes are resized. 


Users should be able to adjust the sash using either a mouse or a keyboard operation. 
Moving the sash with the mouse is typically a button—press, drag, button—release operation 
like moving a window using the title area. Moving the sash with the keyboard typically 
requires a selection and the use of the navigation keys. 


Choosing the Appropriate Control 
Radio buttons, option menus, and list boxes can all be used to choose one option from a list 
of multiple options. Choosing the right control for the job depends on the number and nature 
of the options in the list. 


For choosing a sing'e option from among a smal Humber Gf Mutually Exciusive Options, a 
radio button is usually the easiest for users to operate. For more options, an option menu 
push button takes up a small amount of space and is relatively easy to use. For many 
options, the list box is the easiest for people to use; it also allows multiple items to be 


chosen at one time. 


Deciding Between a Pop—Up Menu and Push Buttons 
Pop—up menus provide users with quick access to application functions. So do control 
panels containing push buttons. Generally, pop—up menus are preferable when users are 
focused on their work areas. In these situations, moving the mouse between a control panel 
and the work area would be distracting. 


Push buttons and a control panel are preferable when users make frequent selections, need 
to make several selections at the same time, or are already manipulating the mouse 
primarily in the control panel area. 
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Deciding Between Dialog Boxes and Menus 
You should design your application so that it is consistent with other AlXwindows 
applications. To do so, you should understand when to use dialog boxes and when to use 
some other method of control. In particular, you should know the difference between dialog 
boxes and menus. 


As you design your application, you will encounter many instances in which the same 
objective can be accomplished with either a dialog box or a menu. The menu selections act 
similar to the controls used in most dialog boxes. However, there are differences. 


A menu is short-lived. It appears quickly, but exists only while a selection is being chosen. 
As soon as the selection is made, the menu disappears. A dialog box, on the other hand, 
can be displayed until told to go away, but usually takes up more workspace. While the 
dialog box is displayed, users can make several different selections. 


Additionally, a menu is usually modal in nature. Until a menu goes away, users can’t interact 
with any other part of the application. Dialog boxes, on the other hand, are frequently 
modeless. Users can still interact with other parts of the application while the dialog box is 
displayed. 


Thus, if a modeless state were required, a modeless dialog box would be the appropriate 
solution. In the case of users browsing current settings or making a single selection, a menu 
would be faster. However, when several selections need to be made, a dialog box would be 
a better design choice. 


Aligning Columns of Controls 
While push buttons are usually placed in a row along the bottom of the dialog box, check 
buttons and radio buttons are frequently placed in columns. When using columns, align the 
check buttons or radio buttons vertically so that the location cursor doesn’t bounce around 
as users tab through the selections. Proper vertical alignment also enables users to slide the 
mouse pointer in a single direction rather than having to move ail over the window to reach 
misaligned controls. 


Using Defaults Consistently 
Your application should use default values for common settings or obvious selections. A 
default selection should be easily distinguishable from other selections. Typically this is 
accomplished with an extra border around the default selection. 


Default check buttons need only display with a check in them. The default selection in a set 
of radio buttons also displays selected. A default push button is typically indicated by a 
double border. Users activate the default push button by double-clicking the Select mouse 
button with the mouse pointer in the area containing the push button or by pressing the 
Enter key on the keyboard. 


| Question Dialog Box 





Default Selection 
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Understanding AlXwindows Application Graphic Controls 


Users control applications in the AlXwindows environment using a number of graphical 
controls. These controls are of the following three types: 


Buttons Like the control buttons in real life, users generally operate AlXwindows 
graphical control buttons by pressing them with the Select mouse button or 
the Select key. 

Boxes Like boxes in real life, graphical control boxes generally contain groups of 


related items 


Valuators Like some analog gauges in real life, valuators provide users with a way to: 
specify or control incremental changes. 


Types of Buttons 
AlXwindows applications currently use three types of buttons: push buttons, radio buttons, 
and check buttons. Which button you use for your application depends on the situation you 
wish to control. Buttons should be of a size large enough so that users can easily position 
the mouse pointer on them. 


Push Buttons 
A push button consists of two parts: 


e A graphical image that represents the button. 
e A label or icon describing the action invoked by the button. 


When users position the mouse pointer anywhere on a push button and click the Select 
mouse button, or position the location cursor on the push button and press the Select key, 
the action represented by the push button occurs. 


The label of a push button should be short, usually a verb for action push buttons, such as 
Cancel or Apply. Response push buttons can have text such as OK or Yes, however, the 
question that prompts the response should be carefully worded to avoid ambiguity. 


A push button can be used to display another dialog box. This is the case with an option 
menu in a dialog box. A push button used this way should provide a visual cue to its 
functionality by following its button label with an ellipsis (...). 


Radio Buttons 
A radio button consists of two parts: 
e The graphic image that visually represents the button. . 
e A label that describes the choice represented by the graphic image. 


Each radio button represents a single—-choice selection. Radio buttons are always in a fixed 
set of at least two buttons and always represent mutually exclusive choices. 


Conceptually, radio buttons work like the buttons on a car radio (from which they derive their 
name). Users select or deselect a radio button by clicking the Select mouse button when the 
mouse pointer is over the radio button or by pressing the Select key when the location 
cursor is over the radio button. Like a car radio, when one radio button is selected, the 
previously selected button is deselected. 
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Radio buttons that refer to similar kinds of options should be grouped in sets. Sets of radio 
buttons that refer to different kinds of options should be grouped separately. Sets can be 
arranged in either rows or columns. Use white space to visually separate multiple sets of 
radio buttons into a control panel. 


Radio buttons are usually circles in 2-dimensional environments and usually diamonds in 
3—dimensional environments to distinguished them visually from check buttons which are 
usually square. 


Check Buttons 
A check button consists of the following two parts: 


e A square box or button that is empty when deselected but that is filled in or contains some 
other visual cue when selected. 


e A label that identifies the purpose of the check button. The label is at the same level as 
and to the right of the check button. 


A Check button enable users to select choices that are not mutually exclusive. Users select 
or deselect a check button by clicking the Select mouse button when the mouse pointer is on 
the check button or by pressing the Select key when the location cursor is over the check 
button. 


[mm Bold 
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[| Underline 





Types of Boxes 
AlXwindows applications currently use two types of control boxes: list boxes and entry 
boxes. Like buttons, which box you use depends on the situation. 
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List Boxes 
A list box typically consists of the following parts: 


e A title that describes the purpose or contents of the list box. The title generally appears 
above the list box. 


e A window containing the listings. 


e Vertical and horizontal scroll bars, as needed. The scroll bars enable users to view the 
listings. 


List boxes enable users to select from an existing list of items that is either long or variable 
in length. 


North Car 
North Dak 
Ohio 
-Qklahoma 
|Oregon | 
Pennsylva 


Rhode Isl 
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Search for: 


Users move the slider on the scroll bar to change their current view of the list. To choose a 
selection, users position the mouse pointer on the selection and click the Select mouse 
button or position the location cursor on the selection and press the Select key. The standard 
methods for range and additional non-contiguous selections are also supported. 





List boxes do not support mnemonics. Instead, they have a speed—search function that 
works as follows: When users type the first letter of an item in a list box, the box scrolls to 
the first occurrence of an item inat begins wiih that ieiier. For exampie, if the list box 
contained an alphabetical listing of the states in the United States, a user would press the O 
key to view the states beginning with Ohio. 


A list box can also be combined with an entry box to provide an incremental search function. 
For example, if the list box contained an alphabetical listing of the states in the United 
States, a user would press the O key to view the states beginning with Ohio. If the user then 
typed Or, the list would move to Oregon. 


Double—clicking the Select mouse button in a list box chooses a selection and activates the 
default push button in the dialog box. 


Entry Boxes 


An entry box consists of the following parts: 


e A title or label. 
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e The box in which text is entered. 


Entry boxes enable users to enter text. The entry box may scroll horizontally if the text 
entered is longer than the box. The entry box may also be more than one line high, in which 
case it can have a vertical scroll bar like a list box. 


The title describes what is to be entered in the entry box. Titles generally appear above or to 
the left of the box (in western countries). 


en 0) 


Word Description: 


Find this word: 


When users move the mouse pointer into an entry box, the mouse pointer changes from the 
default shape to the shape of the text insertion cursor. Entry boxes follow the rules for basic 
text editing. 





Pending Delete 


Entry boxes include a function known as pending delete. Using this function, users can 
select a range of text to be overwritten in an entry box and then simply begin typing the 
replacement text. The selected text is deleted and the new text is inserted in its place as 
typed. 


Text Cursor Shapes 


A text insertion cursor shows where text will be inserted or overstruck. Insertion cursors 
should always provide users with a visual cue to the current text mode, insert or overstrike. 


In insert mode, the cursor typically appears as a vertical bar or pipe (|) between two text 
characters. When users press a new character, the character appears to the left of the 
cursor. The cursor moves one character space to the right. In an inactive window or entry 
box the insertion cursor is de-emphasized. 


In overstrike mode, the cursor typically appears as a block or underline located at the text 
character that will be replaced. When users press a new character, the cursor replaces the 
existing character with the new character and moves to the right to the next character. In an 
inactive window or entry box the block is not emphasized. 
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Typical text cursor shapes are shown in the figure. 


Active 


Inactive 





Your application should allow users to control whether insertion cursor blinks or not. 


While several insertion cursors may appear on the workspace, only one cursor, the one in 
the window with the input focus, can be active; all other insertion cursors are inactive and 
have a de-emphasized shape. 


An insertion cursor can change size and should be set to the height of the current font. 


Pre—formatting Entry Areas 
Where possible, the entry boxes of your application should be pre—formatted. Typical 
instances are entry boxes for supplying phone numbers or social security numbers. 
Preformatted entry boxes increase the uniformity of the data entry while easing the burden 
of remembering and correctly typing formats. 


When the text entered in an entry box is all the same length (for example, phone numbers or 
social security numbers), you can implement auto tabbing. Auto tabbing speeds data entry 
in fixed-length fields by automatically moving the cursor to the next field as users finish 
making an entry in the current field. This saves moving the mouse or pressing the navigation 
keys. 


Types of Valuators 
The AlXwindows includes several types of valuators that enable you to provide users with 
analog-—style controls. 


Using a Scale : 
Your application could use a scale valuator. A scale enables users to enter a value from a 


range of values by adiusting in analog fashion a sliding afrow io a specific position aiong a 
line. 
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A scale valuator consists of the following components: 


Scale bar The scale bar may contain tick marks and represents the range of available 
values. 
Slider The slide arrow marks the currently chosen scale value. 


Digital readout The digital readout is an optional number directly opposite the slider that is 
the digital representation of the currently chosen analog scale value. 


Using a Scroll Bar 
People use scroll bars to scan rapidly through the contents of a window or to choose from a 
continuously variable set of values such as color intensity. The current location or setting of 
the scroll bar is shown by the position of the slider in the scroll bar for text windows or by 
example for variable choices such as color intensity. 


If users try to scroll beyond the end of the text, nothing should happen. 


Scroll Bar Components 
Scroll bars have the following components: 


Scroll region The scroll region is the “background” of the scroll bar and represents 
visually the length of the area that users can scroll. 


Slider The slider represents the window through which users look at the displayed 
data. Put another way, the position of the slider box on the scroll region 
provides a visual cue that marks the location of users’ viewpoint in relation 
to the total scrollable area. 


Stepper arrows 
The stepper arrows enable users to scroll incrementally through the data 
and provide a visual cue to the direction of the scrolling movement. 


Your application can use either horizontal or vertical scroll bars or both. The slider moves 
back and forth in the scroll region showing the position of the currently displayed section 
relative to the entire contents. 
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Operating Scroll Bars 


Viewing text or graphical information through a window is like viewing the stars through 
binoculars. To change the view of the sky, users move the binoculars, not the stars. When 
the binoculars move up, the stars appear to move down; whichever direction the binoculars 
move, the stars appear to move in the opposite direction. Similarly, when people use a scroll 
bar to view a file, the file appears to move in the direction opposite to the movement of the 
slider. For example, in a text window, if the slider of a vertical scroll bar moves up, a text 
display seems to move down as previous lines in the file appear at the top of the window. 


The following list discusses the different ways users can operate a scroll bar. 


Action Description 
Performing a selection operation Highlights the stepper arrow and moves the 
on a stepper arrow. window through the underlying file by a single 


unit, in the direction indicated by the arrow. 


Performing a press selection operation Highlights the stepper arrow and causes a 
on a stepper arrow. continuous scroll, in unit steps, in the direction 
indicated by the arrow. 


Performing a selection operation Moves the window through the underlying file by 
on the scroll region. one window length minus one unit for overlap. 


Performing a press selection operation Continuously moves the window through the 
on the scroll region. underlying file by one window length minus one 
unit for overlap. 


Performing a drag selection operation Moves the slider and continuously moves the 
on the slider. window to a location consistent with the new 
slider location. 


Automatic Scrolling 


When users drag the mouse pointer (with a mouse button pressed) beyond the top or 
bottom of the window, your application should continue the selection by scrolling in the 
direction of the mouse pointer. This automatic scrolling operates at the same speed as when 


4—36 AIX User Interface Programming Concepts 


users press on the directional arrows. The automatic scrolling ends when users move the 
mouse pointer back into the window or release the Select mouse button. 
Slider Size 


The slider itself may vary in size to represent the proportion of the entire contents currently 
covered by the window. 


Scroll bars are usually located to the right or on the bottom of the area to be scrolled. 
Application Extras 
Besides the controls supplied by the AlXwindows toolkit, other dialog box controls can be 


supplied by the application as needed. One such application extra is the stepper button. A 
stepper button typically consists of the following parts: 


e A title or label. 


e A group box or panel separating the stepper button visually from the other parts of the 
dialog box. 


e A text box displaying the current value of the stepper button. 
e A scroll bar for stepping through the list of values to find a new value. 


A stepper button enables users to select a value by scrolling through a circular list of 
possible values. The stepper button is similar in operation to the digital readout of a stereo 
tuner where pressing the button steps the read—out through the available radio stations. 


The values that read out as people use the stepper button can be either letters or numbers, 
but they should be in consecutive order, either alphabetical or numerical, as opposed to 
random order. Users should be able to anticipate the appearance of values. 





Combining Controls 
Entry boxes and list boxes are often used in combination to provide users with particular 
capabilities. Some common examples are the following: 


incremental searching As users type each letter of an entry in the entry box, the list 
box moves to the part of the list that matches what has been 
typed so far. When the desired item appears in the list box, 
users click the Select mouse button to select the item. The list 
box can still be used in the normal way. 


automatic entry Users scan the items in the list box and click the Select mouse 
button to put the current item in the entry box. The entry box 
can still be used in the normal way. 


List boxes used in incremental searches or in automatic entry must be single selection. 


Chapter 4. AlXwindows Style Guide 4-37 


Understanding AlXwindows Menus 


A menu typically consists of a title and a list of selections. Similar to restaurant menus, 
menus in the AlXwindows environment display a list of selections from which the user 
chooses an appropriate action. Menus provide the user with a simple means to quickly 


access the functions in your application. This article discusses the following aspects of 
menus: 


e What types of menus there are 
e What components make up menus 
e How users operate menus 


e What are the standard AlXwindows menus 


How to design AlXwindows menu extensions. 


What Types of Menus There Are 


The AlXwindows environment has the following four types of menus: 

Pulldowns Menus that pull down from a fixed location in the menu bar. 

Option Menus that display from a an option button in a window. 

Popups Menus that pop up at the current pointer location, wherever that may be. 


Cascading Menus that cascade to the right from another menu, providing more detailed 
selections related to the original menu selection. 


Pulldown Menus 


In most cases, pulldown menus provide an important part of the communication between 
users and application programs. 


re 


Edit View | Help 


New 


| Open... | 


Save As... 










Print 
Exit 


Pulidown menus, with the exception of the window menu, are always associated with an 
application’s menu bar. The result is that, if you design your application to include a menu 
bar, the titles of available pulldown menus are always visible to the user running your 


4—38 AIX User Interface Programming Concepts 


application. Thus, the major portion of the functionality of your program is only a 
point-and-click (or point—-and—drag) away from the user’s fingertips. 


Additionally, the user soon learns to drag the pointer across the titles in the menu bar, 
displaying each pulldown menu in turn, thus providing a handy table of contents to your 
application’s functionality. This is another way of giving the user control as it enables the 
user to browse your program’s functionality, refreshing their memory, rather than forcing the 
user to remember the arcane command-line syntax of a particular function. 


Option Menus 
Windows which include selections from a list, but where space is at a premium are 
candidates for option menus. Only the option button is usually visible. The button shows the 
current value of the control. When users select the option button, the menu appears, 
showing the list of choices. 


Enter Stylesheet to use: 
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Popup Menus Save Space ) 
Popup menus are also called context menus and have the advantage that they take up no. 
permanent screen space. Not being associated with a menu bar, they simply pop up at the 
current pointer location. A workspace menu is an example of a popup menu. 
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A second advantage of the popup menu is that it requires a minimum of mouse movement.. 
To display a pulldown menu, the user must position the pointer on a title somewhere in the 
menu bar; to display a popup menu, the user need only press the Menu mouse button. 


Popup menus are related to the context of the area in which they are selected. For example, 
a workspace menu that pops up when users position the pointer over the workspace and 
click the Menu mouse button may be associated with system-wide functions. 


However, popup windows, by their very nature, do not provide a visual cue to their 
availability. The user must learn and remember that a popup menu is associated with a 
certain area. Therefore, your application design should not use popup menus too casually. 


Cascading Menus Provide Further Selection Detail 
Cascading menus add detail to pulldown and popup menus. You can think of them as 
submenus or child menus of other menus. Cascading menus provide you with a mechanism 
to organize menu selections in a tree structure, thus simplifying the presentation of complex 
selection lists. To maintain ease of use, the menu section tree should be no more than three 
levels deep. A cascading menu appears when users select or drag the pointer onto or 
across its title on the parent menu. 


Workspace Menu 


Graphics Tools -»/}| Color Wheel... 


Text Tools -» | Graphics Editor 
Remote Logins -» | FontSelector » 
Refresh Workspace | PropsMenu > 





Cascading menus typically appear to the right of their parent menu selection. While 
cascading menus differ from the two other types of menus in the method of their 
appearance, cascading menus behave just like pulldown and popup menus as far as the 
choosing of a selection. 


What Components Make Up Menus 


All menus, regardless of type, have the same components. 


Menus have titles that name them. A menu’s title should be unique to eliminate the 
possibility of confusion. The title should clearly indicate the purpose of the menu. 


The title of a pulldown menu is on permanent display in the menu bar. The optional title of a 
popup menu displays at the top of the menu. The title of a cascading menu displays as a 
selection in the parent menu. 


The titles of pulldown menus that appear on the menu bar employ single—character 
mnemonics as memory aids to increase the efficiency of the more experienced user. 
Mnemonics are explained later in this section. 


Menu titles are visually distinct (that is visually separated in some way) from the menu’s 
selections. Typically, this is accomplished by placing a separator line below the title. 
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Menus Have Selections 
Menu selections are listed below the menu title and, like the titles of pulldown menus, can 
also employ mnemonics. Additionally, a menu selection lists any keyboard accelerator 
associated with the selection. Selections can be text or graphics. Selections can also be 
grouped with a separator to provide a visual cue of similarity or related functionality. 


AlXwindows menu selections can be one of three types. as shown in a sample menu 
containing the three selection types. 


Type Description 
Actions Issue a command or carry out an action. 
Routings Display a dialog box (dialog menu items are indicated by an ellipsis (. . .)) or 


a cascading menu (cascading menu selections are indicated by an arrow 


(—>)). 


Settings Set an application state using check buttons (multiple selections) or radio 
buttons (mutually exclusive selections). 











Action 
Submenu > 
Routings : 
Dialog Box... 
Radio Button 
Settings 


Check Button 


<> Radio Button 
(om) 
[mg] Check Button 


Menu selections that are currently not available (disabled) are visually de-emphasized. 


Menus Have Mnemonics 
A mnemonic is a single character that provides a shortcut for making selection from the 
keyboard. Users press the mnemonic for a selection rather than using the navigation and 
select keys. In the AlXwindows environment, all menus (and the titles of pulldown menus on 
the menu bar) have mnemonics associated with their selections. AlXwindows menu 
mnemonics are a single letter, usually the initial letter of the selection. Typing the mnemonic 
for a selection chooses that selection, the same as if the selection were chosen with a 
mouse operation. If the title of a cascading menu is selected, the menu is displayed. To 
display a pulldown menu while the location cursor is outside the menu bar, press the Alt key 
and the mnemonic key, for example Alt+F4 to close a window. 
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Move... Alt+F7. | -— Current Selection 
Size Alt + F8 
Minimize Alt + F9 

Alt + F10 Accelerators 


Alt + F3 


Alt + F4 


Typically, an underline visually designates a letter as the mnemonic for a selection, as shown 
in the figure. When an initial letter cannot be used, as in the case where two selections begin 
with the same letter, some other letter in the selection name, preferably with some 
mnemonic value, should be chosen instead. If the mnemonic letter does not appear in the 
selection’s text, it appears in parentheses after the text. 


Mnemonics are only accessible when the menu containing them is displayed. The pulldown 
menus in a menu bar are always accessible (by pressing Alt+mnemonic) since the menu bar 
is always displayed. 


Menus Have Keyboard Accelerators 


Menu selections can also have keyboard accelerators, a key or key sequence that invokes 
a menu selection without displaying the menu. Keyboard accelerators do not have to be 
associated with each and every menu selection. In most cases, it is sufficient to provide 
accelerators only for frequently used functions. Providing accelerators should be a matter of 
utility, not design conformity. 


If a keyboard accelerator exists for a menu selection, it appears right justified on the same 
line as and separated from the selection’s text by enough space to make it visually distinct. 
Other than this, keyboard accelerators provide no visual cue to their existence and so users 
must memorize them. This is why frequently used functions make the best candidates for 
accelerators. 


How Users Operate Menus 


Users operate menus in two steps: first, they display the menu; second, they choose a 
selection. When a selection has been chosen (unless it leads to a cascading menu), the 
menu disappears. 


Displaying Menus 


In the case of pulldown menus, mouse users move the pointer to the title of the menu and 
press the Select mouse button. Keyboard users move the location cursor to the menu bar by 
pressing the F10 key, then press the pull down menu’s mnemonic or use arrow keys to 
select the menu’s title. An alternate method of displaying a pull down menu is to press the 
Alt modifier key and press the menu mnemonic. 


In the case of popup menus, mouse users move the pointer over the popup area (for 
example, the workspace) and press the Menu mouse button. Keyboard users press the 
Menu key to display a popup menu. 
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In the case of cascading menus, mouse users move the pointer to the title of the cascading 
menu on the parent menu and click (or continue to press) the Select mouse button. 
Keyboard users use the navigation keys and the Select or Enter keys to achieve the same 
effect as the mouse user’s actions. 


Additionally, the user can access application menus using either of the following two 


methods: 

Dragging Drag the menu by pressing and holding down the mouse button to maintain 
a hold on the display. To make a choice, release the mouse button. 

Clicking Click the appropriate mouse button or press the appropriate key to display 


the menu. The menu remains displayed until either a selection is made or 
the display is canceled. A selection is made by moving the pointer to the 
selection and clicking the mouse button or by moving the location cursor to 
the selection and pressing the Select or Enter key. 


Browsing the Menu Bar 
The user can browse the menus listed on the menu bar by pressing the Select mouse button 
and dragging the pointer across the menu titles. As the pointer crosses each title, the menu 
associated with the title pulls down. To browse the menu bar from the keyboard, the user 
displays a menu and uses the left and right arrow keys to move laterally across the bar. 


Choosing Menu Selections 
To choose a menu selection, the user positions the pointer or location cursor on the 
selection and makes a selection action. 


A person using the drag method drags the pointer onto the selection desired and releases 
the mouse button they pressed to initiate the drag process. 


A mouse user using the click method slides the pointer onto the selection and clicks the 
appropriate mouse button. 


A keyboard user using the click method uses the navigation keys to position the location 
cursor on the selection desired and presses the Select key. 


A menu item that has been selected provides a visual cue of its selection. Typically, this cue 
is a change in color, either highlighting or reversed video. In a 3—D implementation, the 
current selection not only changes color, it also has a raised, 3—-D appearance. 


Releasing the mouse button or keyboard key selects the item under the mouse pointer or 
location cursor. If the release occurs on a command (action), check button, or radio button, 
the specified action takes place, and any menus displayed disappear. If the release occurs 
on the title of a submenu, the menu is displayed. 


Avoiding Menu Selection 
To avoid making a menu selection, a mouse user dragging the menu drags the pointer off 
the menu and releases the mouse button. A mouse user clicking the menu slides the pointer 
off the menu and clicks the Select button. A keyboard user presses the Esc key. 


The Standard AlXwindows Menus 
The following five pulldown menus provide general functions common to most applications. 
They are a part of most menu bars in the AlXwindows environment: 


e File 
e Edit 


e View 
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e Options 
e Help 


= AlXwindows | Oli 





Options 








The File and Edit menus have recommended contents. The View and Option menus are 
highly specific to each application, so only sample implementations are provided. This 
chapter also contains a sample Help menu. You can create additional menus for your 
application. The File and Edit menus (if used) should be the first two menus in your action 
bar. The Help menu is always the last. 


While it is recommended that you include the standard menus in the menu bar of your 
application, your choice of menu titles and items depends on the nature of your application. 
Should your application require it, you should design more relevant titles and selections for 
your application’s menu bar and menus, but do not change the meanings of words used in 
the standard menus. 


A Look at the File Menu 
The File menu presents actions that deal with files in their entirety. All applications that deal 
with files should provide the File menu. 


The selections in the menus are divided into four groups: 


e Selecting actions that connect files to your application. 


Saving actions that transfer changes made to a storage medium. 
e Output actions that send the changed file to an output device. 
e Other actions. 


These groups are important as you design extensions to the menu. Suppose you wanted to 
add an action called Plot to your application. You would place it in the File menu because it 
deals with the file as a whole. Within the File menu, you would place it with Print in the 
output group because Plot writes the entire file to an output device. 
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For consistent operation with other AiXwindows applications, if you include the File menu in 
the menu bar of your application, it should appear as the first title, placed on the far left, and 
with F as its mnemonic. . 


The File menu contains the following selections: 


New Creates a new file. The New operation clears existing data from the client 
area and replaces the current filename in the title bar with Untitled or some 
other application—generated name. If completion of the operation will 
obliterate current changes to the file, you must display a message box 
asking users whether they want to save their changes. 


Open... Opens an existing file. The Open operation prompts users for the name of 
the file by displaying a dialog box for the purpose. The title bar is updated 
with the name of the newly opened file. If completion of the operation will 
obliterate current changes to the file, you must display a message box 
asking users whether they want to save their changes. 


Save Saves the currently opened file to a storage device without removing the 
existing contents of the client area. If the currently opened file has no name, 
Save prompts users for a file name by displaying a dialog box for the 
purpose. Saved along with the file should be the current state of the file, 
including: window size, window location, and scrolling position within the file. 
This enables users to reopen the file and begin their work where they left 
off. 


Save As ... Saves the currently opened file under a new name. The Save As operation 
prompts users for the name of the file to be saved by displaying a dialog box 
for the purpose. If users try to save the new file under an existing name, the 
Save As operation displays a warning message alerting them of a possible 
loss of data. 


Print Schedules a file for printing. If your application requires specific printing 
information before printing, the_Print... selection displays a dialog box in 
which to gather it. 
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Exit Ends the current application and closes all windows associated with it. This 
action is equivalent to closing all primary windows of the application. If 
completion of the operation will obliterate current changes to the file, you 
must display a message box asking users whether they want to save their 
changes. 


You are encouraged to include this action even though it duplicates much of the functionality 
of the Close action in the window menu. This assures users have a way to end the 
application even if they are not running the AlXwindows window manager. If your application 
does not have a File menu, put Exit at the end of the first pulldown menu. 


A Look at the Edit Menu 
The Edit pulldown menu contains actions that modify the contents of the data which which 
your application is currently dealing. Many of the actions relate to cut and paste functionality. 


The standard edit selections are grouped as follows: 

e Undo actions that reverse the effect of previous actions. 
e Actions that relate to the system-wide clipboard. 

e Other Actions. 


Fa ee ee eT 
=| —SS~SSampie srt ——SSSSS~wd 
File View Help 


Undo Alt+Backspace 


Cut Shift+Del 


Copy Ctrl+Ins 


Paste Shift+Ins 
Clear 


Delete 





For consistent operation with other AlXwindows applications, if you include the Edit menu in 
the menu bar of your application, it should appear as the second title from the left and with E 
as its mnemonic. The Edit menu contains the following selections: 


Undo (Alt+Backspace) 
Reverses the most recently executed action. To provide a visual cue to 
users, the Undo selection should be dynamically modified to indicate what is 
being undone. If the most recently executed action were a paste, the action 
name would be Undo paste. Your application should be able to undo all of 
the actions in the Edit pulldown. Text applications should also support Undo 
typing which restores text after it has been selected and replaced by newly 
typed text. 


Cut (Shift+Del) Removes a selected portion of data from the client area to the clipboard 
buffer. Your application determines whether the area that used to be 
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occupied by the removed data is left blank or whether the remaining data is 
compressed to fill in the space. Usually graphics applications leave the 
space blank while text application compress the remaining text to fill in the 
space. 


Copy (Ctri+ins) 


Copies a selected portion of data to the clipboard without removing the 
original data from the client area. 


Paste (Shift+Ins) 


Clear 


Delete 


A Look at a View Menu 


Pastes the contents of the clipboard into a client area at the selected 
location. Your application determines whether the pasted data is reformatted 
to fit in the client area and whether existing data moves to create room for 
the pasted data. Text applications will typically reformat the pasted text to fit 
into the margins of the text field and they will move the existing text to make 
room for the new text. Graphics application might do neither. They might 
insert the graphics unmodified and overlay existing data. 


(Optional) Removes a selected portion of data from the client area without 
copying it to a clipboard buffer. Clear erases the data, but leaves the space 
formerly occupied by the data. 


(Optional) Removes a selected portion of data from the client area without 
copying it to a clipboard buffer. The remaining data is compressed to fill the 
space formerly occupied by the deleted data. 


A View menu enables users to control how data is displayed. The data itself remains 
unchanged. Entries in the menu control such aspects of presentation as: 


e Appearance of the data. Examples may be iconic or text-based. 


e How much of the data is presented. 


e in what order the data is sorted. 


e To what level the data is summarized. 


For consistent operation with other AlXwindows applications, if you include a View menu in 
the menu bar of your application, it should have the V as its mnemonic. 


The content of View menus is very application specific. 
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A sample menu for a hypothetical file browser contains the following entries are: 


All Views an entire list of items. 

Partial Views a partial list of items. The selection criteria are determined by a dialog 
box. 

By Date Views a list ordered by date of entry. 

By Name Views a list ordered by item name. 

By Other Views a list ordered by selection criteria determined by a dialog box. 


Remember that the menu above is only an example. The needs of your application control 
what entries you place in your View menu. 


A Look at an Options Menu 
An Options menu enables users to customize various aspects of your application. Just like 


the View menu, the Options menu’s content depends entirely on the needs of your 
application. 


For consistent operation with other AlXwindows applications, if you include a Options menu 
in the menu bar of your application, it should have the O as its mnemonic. 
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The content of Options menus is very application specific. Entries in the menu for a 
hypothetical spreadsheet application might include such entries as: 


Recalculate _—_ Displays a dialog box to control when cell formulas are recalculated. 


Message area A check box that controls whether a message area is displayed. The 
message area shows helpful explanations of commands for novice users. 


Colors... .Displays a dialog box used to select colors used by the application. 
Remember that the menu above is only an example. Select entries appropriate to your 
application. 


A Look at the Help Menu 
Good applications provide help facilities for people to use when the need arises. No matter 
how intuitive you design your application to be, sometimes users get stuck. 


For consistent operation with other AlXwindows applications, if you include a Help menu in 
the menu bar of your application, it should appear as the last title, placed on the far right of 
the menu bar, and with H as its mnemonic. 
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The sample menu contains the following selections: 


On Context Provides context—sensitive help about the specific situation that exists when 
the help was requested. 


On Help Provides information on how to use the application’s help facility. 


On Window Provides general information about the operation of the window from which 
the help was requested. 


On Keys Provides information about the application’s use of function keys, 
"mnemonics, and keyboard accelerators. 
Index Provides an index, with a search capability, for all help information in the 
application. 
Tutorial Provides access to the application’s tutorial if such a tutorial exists. 


On Version Provides the name, version, and date of the application. 


Help windows your application displays generally are normal secondary windows whose 
parent window is the window from which users requested help. The title in the menu bar is 
the name of the application (or name of the object in object-oriented systems) followed by 
the word Help. Help menus may also have a title in the client area that describes the topic 
for wnicn neip is being provided. 


How to Design AlXwindows Menus 
You will most likely have to design menus specific to your application. The following sections 
describe some considerations in menu design. 


Group Like Menu Selections Together 
As a general rule, wherever possible, organize the selections on your menus into logical 
groups. 


However, it’s not a good idea to put a destructive command (such as Delete or Quit) next to 
other frequently chosen selections. This is because of a common problem of menus called 
the off by one error: Users mistakenly choose the selection next to the one they intended to 
choose. So be aware of the result if a user mistakenly chooses the menu selection above or 
below the intended selection. 
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Use a visual cue such as a separator line to divide menu selections into logical groups. 


Sets of related items, such as radio buttons or check buttons, should be located together 
and separated from other menu items. 


List Selections in Order of Frequency 
Order menu selections according to the frequency of usage, positioning the most frequently 
used selections near the top of the menu. 


As much as the logical grouping of the menu allows, order the selections of your menu in 
decreasing frequency of 


usage. Within logical groups, the same principle applies: List menu selections according to 
the frequency of usage with the most frequently used selections at the top. 


As you order menus, maintain a global perspective. Consistency across your entire 
application is generally more important than frequency of use in a particular menu. Evaluate 
frequency of use over the entire environment faced by people who use your application. 


Keep Menu Structures Simple 
If your application requires submenus, keep the menu structure simple. While it is possible 
to create menu structures that start from a single pulldown or popup menu and cascade 
down several levels of submenus, it is seldom necessary to do so. The awe of users who 
see submenu after submenu cascading down the screen quickly turns to consternation over 
such poor design. 


Avoid using many submenus in your application. It is better to use a few more pulldown and 
popup menus, or to have more selections per menu, than to have multiple cascading 
submenus. 


As a general guideline, use as few menu levels as possible with three levels as a maximum. 
A dialog box is a good alternative to menu complexity. So is redesigning your menu structure 
to eliminate complexity. 


Provide Accelerators and Mnemonics 
Keyboard accelerators and mnemonics enable users who have become familiar with your 
application to take short cuts, increasing their efficiency, while not affecting those users who 
are still learning the basics. 


Mnemonics require the display of a menu but are preferred by some users because they 
allow those users to operate the mouse with one hand and make the selection with the other 
(as the mouse hand returns to the keyboard). Mnemonics can be made more memorable by 
carefully choosing the mnemonic letter. 


Keyboard accelerator sequences don’t require the display of a menu, hence they are active 
whenever your application’s window is active. They are designed for menu entries that 

people use very frequently. To make the accelerators for your application more memorable, 
design your application so that accelerator sequences are consistent and progress logically. 


Control Availability of Menu Selections 
During use of your application, the application will enter a state where some menu selections 
will not make sense. In that case, make them unavailable while that state occurs. This 
avoids excessive message boxes noting a selection error. 


Making menu selection unavailable provides a temporary constraint. Menu selections that 
are never applicable to your application should not be included in the menu. 
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Unavailable menu selections provide a visual cue, such as being dimmed, that they are not 
functional in the current context. But even if all selections in a menu are disabled, users 
should still be able to display the menu (but not choose any of the selections) and get help. 


Consider Use of Graphic Images 
An important option to consider is the use of graphic images (bitmaps) for selections. A good 
picture can be more readily understood and easily remembered than a line of text. Graphics 
also ease the task of localizing your application for other countries. 


Keep Menu Selections Stable 
You should generally keep menu selections the same for the duration of an application’s 
invocation. Settings in menus may be set or unset and any selection may become 
unavailable, but the selections themselves should not change. 


Do not replace menu selections during an application’s use. Entries that are temporarily 
unavailable should be disabled and should visually appear as such. 


You may want to reword some menu selections slightly in order to better reflect their 
meaning during the current state of the application. The Undo entry in the Edit menu does 
_ this. 


Adding menu entries dynamically is discouraged. If your application does require this, 
however, add them at the end. Number the selections and use the number as the 
mnemonic. This is the only case where menu selections should be numbered. 


ThE AGve Giscussion of dynamic changes in menus applies only to changes made by the 
application in response to changing conditions in the application. They do not apply to any 
changes due to user customization. 


Allow Users to Customize Menus 
Should you choose to, you can further empower the people using your application by 
allowing them to create their own menu titles and selections and associate them with their 
own choice of functions. 


Understanding AlXwindows Dialog Boxes 


A dialog box is a window that contains graphical controls that people use to converse with 
your application. While the AlXwindows toolkit supplies you with graphical controls for most 
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occasions, you must select the appropriate controls and create the dialog boxes for your 
application. 


The following aspects of dialog boxes are discussed in this overview: 
e The characteristics of dialog boxes 

e Dialog box actions 

e The anatomy of a dialog box 

e Message diaglog box types 

e Common dialog boxes 


e How the user converses with dialog boxes. 


The Characteristics of Dialog Boxes 
People use dialog boxes to control the operation of your application. From a technical point 
of view, a dialog box is any window that solicits or displays information or instructions. While 
dialog boxes are similar to menus, because they enable the user to control your application, 
they can be much more flexible than menus. It is important that you design dialog boxes with 
the needs of your application and your user in mind. 


The Purpose of Dialog Boxes 
Dialog boxes have a variety of purposes. Some display information. These message boxes 
may be rather plain and relatively simple. Other dialog boxes solicit data from the user. 
These may include elaborate combinations of text and graphics and a variety of controls 
(entry boxes, list boxes, radio buttons, etc.) through which the user conveys information to 
your application. 


You are not restricted to these purposes. In fact, many of your dialog boxes may serve a 
combination of purposes. However, you will probably notice that many of your dialog boxes 
require the same or similar actions. Dialog Box Actions describes standard dialog actions. 
Your application should take advantage of these when appropriate. 


Ending a Dialog 
Many dialog boxes disappear after the user acknowledges the information, provides the 
information requested, or selects an action. This is another area in which dialog boxes are 
similar to menus. Unlike menus however, you may want a particular dialog box to remain 
visible after a selection. This enables the user to continue the dialog without having to 
redisplay the dialog box. The Find String dialog box of some editor programs is an 
example. It remains visible until the user explicitly closes it. 


Making Controls Unavailable 
As people use your application, the operational context that develops may make the use of 
certain controls inappropriate. For example, the use of the Minimize selection in a window 
menu is inappropriate when the window is already minimized. In such cases, you should 
make the inappropriate controls unavailable. This is also called disabling the controls. 
Unavailable controls are visually de-emphasized. The unavailable controls can be in any 
window of your application. While unavailable controls do not operate, the user should still 
be able to get help on them. 


If a control can never be used, that control should not appear at all. Applications that have 
various authorization levels, for instance, should only show those controls the user is 
authorized to use. 


Some dialog boxes require the user to complete the interaction with them before the 
application continues. In essence, these dialog boxes temporarily disable all other controls in 
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the application. This type of dialog box is sometimes called application modal. Others take 
over the entire display and make all other windows on the screen unavailable. These 
windows are called system—modal. Message boxes that require the user to perform some 
immediate action before processing can continue are examples of modal windows. Use the 
disabling feature sparingly, since it compromises the basic premise of the AlXwindows 
interface: empowering the user. 


Dialog Box Actions 
Most often dialog boxes present information or solicit data. Typically, they also provide 
several actions from which the user selects the action desired. 


While on occasion your application may require special dialog box actions, most of your 
dialog boxes will share common actions. The AlXwindows user interface has identified 
actions that are likely to occur in many dialog boxes and has given them common names 
and definitions. No dialog box will contain all of the common actions listed below. Select the 
ones appropriate to your application or determine your own actions using the guidelines in 
this section. The list is ordered in the approximate sequence they appear in dialog boxes. 


Action Performs the action specified by the label. You specify actions that are 
appropriate to your application. 

Yes Indicates an affirmative response to a question posed in the dialog box and 
closes the window. See note below. 

No Indicates a negative response to a question posed in the dialog box and 
closes the window. See Note: at the end of this list. 

OK Combines Apply and Close actions (both are described below) in one 
convenient push button. 

Apply Applies any changes made to controls in the dialog box. 

Retry Causes the task in progress to be attempted again. This action is commonly 
found in message boxes reporting some sort of hardware error. 

Stop Ends the task in progress at the next possible breaking point. This action is 
commonly found in progress message boxes. 

Text... Opens another dialog box that extends the current dialog. 

Reset Resets any changes to controls in the dialog box to the values they had 
when the dialog box was opened. 

Cancel Combines Reset and Close actions in one convenient pushbutton. 

Close Removes the dialog box. The user explicitly closes dialog boxes that remain 


open after each use. This function duplicates the Close action in the 
window menu of the dialog box. You are encouraged to include it in your 
dialog box in case the user runs your AlXwindows application without the 
AlXwindows window manager. 


Help Enters the help subsystem. 


Note: While Yes and No are not actions, they imply do and do not and are used in dialog 
boxes in that context. However, you should be careful to avoid ambiguity. Only if a 
question is very simple, phrased without negatives, and results in an action that is 
not damaging should you use Yes and No. Otherwise, use an action. 


The Anatomy of a Dialog Box 


Dialog boxes are composed of combinations of the controls described in AlXwindows 
Application Graphic Controls Overview. 
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Dialog boxes differ from one another, not because their controls differ. Controls do not differ 
in behavior. A push button, for example, is always pushed; a check button is always 
checked. This is fundamental to common behavior. Rather, dialog boxes differ because your 
choice of controls and combinations of controls differs depending on the needs of your 
application. 


Text Entry Box Radio Buttons Check Buttons 
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Option Menus Push Buttons 


While the AlXwindows Toolkit provides a variety of standard controls, you can create 
additional controls should the need arise. A stepper button is an example of an application 
supplied control. 


Arranging Push Buttons in Dialog Boxes 
You should arrange push buttons in your dialog box in in an order that supports the user’s 
natural progress through the controls in the dialog box. This guideline usually results in 
pushbuttons either in a row at the bottom of the window or in a column at the right . 


Of the two positions, in a row along the bottom of the dialog box is preferable because push 
buttons are frequently used to end the dialog and thus are the last thing the user encounters 
as the contents of the dialog box are scanned. 


Push buttons are commonly found in the following combinations and sequences: 
e Close 

e OK Cancel Help 

e OK Reset Cancel Help 
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e Apply Reset Close Help 
e Yes No Help 
e Retry Stop Help 


In this order, the positive (confirming) selections are toward the left, the selections negating 
change are toward the right, and Help is consistently placed as the right most push button. If 
you choose to arrange push buttons in a column, the positive selections should be toward 
the top with Help on the bottom. 


Default Push Buttons 


A default push button enables the user to easily select the most likely response to a dialog 
box query. The default push button is always visually distinguishable from other push button 
selections. The OK push button is frequently the default push button in dialog boxes. 


If possible, the action performed by the default push button should be reversible. If an action 
is potentially destructive (for example, if loss of data could occur), its button should not be 
made the default push button. 


Ee Question Dialog Box 


? Do you want to switch mailboxes? 





Default Selection 
The user can start the default push button action in either of two ways: 
e By double-clicking when making a selection in the dialog box. 
e By pressing the Enter key after making a selection in the dialog box. 


When people use the keyboard to navigate through the push buttons, the button with the 
location cursor always becomes the default push button. This ensures that pressing the 
Enter key over a push button invokes that push button. When the location cursor leaves the 
push buttons, the original default button once again becomes the default. 


Message Dialog Box Types 


Information 


Some dialog boxes provide the user with a message and ask for an acknowledgement or 
response or some sort. These dialog boxes, called message boxes, are not requested by the 
user, but are displayed by an application as a result of some event. The dialog boxes can be 
divided into five general types depending on the nature of their message: information, 
progress, question, warning, and action. 


Some dialog boxes simply convey information. They inform the user. The information dialog 
box does not interrupt any tasks. For example, they may display the fact that a user has 
newly arrived electronic mail. When the user acknowledges the information, the 
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Progress 


Question 


Warning 


information box goes away. A typical information dialog box that conveys information is 
illustrated. 


I Guess what? You’ve got mail! 





Other dialog boxes convey current progress. The message displayed by a work-in-progress 
dialog box tells the user of the progress of an operation and allows the user to choose 
between continuing the operation or canceling it. A typical work—in—progress dialog box that 
conveys the status of work in progress is illustrated. You may want to show in your 
application's progress box how much of the total work has been completed. 


| Work-in-progress Dialog 








Some dialog boxes clarify a previous response by asking a question. The work does not 
proceed until the question has been answered. The question briefly explains the situation 
and is phrased so that the reply is a choice between mutually exclusive alternatives. A 
typical question dialog box that asks a question is illustrated. 


a 
oP 


= Do you want to switch mailboxes? 





jt 


Other dialog boxes convey a warning. The warning dialog box alert the user to some 
eminent danger (for example, the potential loss of data) and allow the user to choose 
between ignoring the warning and continuing the operation or heeding the warning and 
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canceling the operation. A typical waning dialog box that warns of possible danger is 
illustrated. 





Action 
Still other dialog boxes convey a message that requires immediate action. They alert the 
user that some action is required (or that some condition exists that requires action) by 
constraining the operation of the application until the action has been completed. A typical 
action dialog box that conveys an action message is illustrated. 


| Action Required! 


Oops! Your mailbox is full! 
You need to answer your mail or switch to a different mailbox. 





Common Dialog Boxes 
Some dialog boxes perform an operation based on supplied input. Usually, these dialog 
boxes are application specific, but some operations are common to a wide variety of 
applications. Examples include operations to save a file, enter a command, and make a 
selection. 


File Selection 
The File Selection dialog box is used by the user to enter ine name Of a file to Save. A 
sample File Selection dialog box is illustrated. The box is most commonly used in 
conjunction with the common File menu described in Understanding AlXwindows Menus. 
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=| File Selection Dialog 


File Filter 


/users/grinch/graphics/ 
/users/grinch/graphics/—display 
/users/grinch/graphics/newfonts 
/users/grinch/graphics/fractals 


/users/grinch/graphics/grinched 
/users/grinch/graphics/outtolunch 
/users/grinch/graphics/inmeeting 


Selection 


/users/grinch/graphics/ 





Command 
The Command dialog box is used by people to enter a command either to the application or 
to the computer operating system. The Command dialog box provides the same function as 
a command line prompt and provides a history list from which previous commands can be 
reselected. Your application should use either the command line or the command dialog box. 
A typical command dialog box is illustrated. 
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Ee Command Box 


Enter Command Here: 


pO 


The Selection dialog box is used by people to choose from a list of several possible 
selections. A typical Selection dialog box is illustrated. 


=| Selection Diatog | 0 | 





Selection 














/users/grinch/graphics/ 
/users/grinch/graphics/ 
/users/grinch/graphics/—display 
/users/grinch/graphics/newfonts 
/users/grinch/graphics/fractals 
/users/grinch/graphics/grinched 
/users/grinch/graphics/outtolunch 
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Selection 


/users/grinch/graphics/ 
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Starting a Dialog 
In general, dialog boxes are started by the user choosing selections from controls such as 
menus. Menu selections that lead to dialog boxes follow the selection name with ellipsis (...) 
as a visual cue. 


In the case of message boxes, the opposite is true. The application starts the dialog box 
based on some event. In the case of information and progress boxes, work progresses 
unimpeded by the presence of the dialog box. For the others, work on a task cannot proceed 
until a question has been answered, a warning of potential damage acknowledged, or some 
specific action taken. 


Navigating Through a Dialog Box 
In many cases, the user does not need to have a long—winded conversation with a dialog 
box to produce results. Rather, the user calls the dialog box from the menu, makes a few 
changes to some settings, and sends the dialog box away. Availability of an appropriate 
default action is key to ease of use. 


Your application should provide the user with the ability to carry on a selective conversation 
with a dialog box and to easily navigate through the box. The mouse user slides the pointer 
directly to a control. The keyboard user presses the Tab and Arrow keys to step through a 
dialog box. 


Determining Dialog Box Location and Size 
Your application determines the size and location of its dialog boxes. 


Location 


Whenever possible, do not place a dialog box so that it obscures important information in the 
underlying window. A dialog box should be horizontally offset from the underlying window. 
This enables the user to see the chosen selections. 


When a dialog box relates to an item in an underlying window, position the dialog box next to 
the item. As much as possible, avoid covering information in the underlying window that the 
user might refer to in conversing with the dialog box. 


If it is necessary to display two dialog boxes, offset the top dialog box (the one that was 
called last) to the right and below the title of the underlying dialog box (the one that was 
called first). 


Obviously, there is only a limited amount of screen real estate in which to place a dialog box. 
While the above suggestions seem simple enough, they can not always be followed 
completely. Therefore, dialog boxes, once displayed, should be movable so that the user can 
relocate them as needed to see information in underlying windows. 


Size 


The initial size of a dialog box should be large enough to contain the dialog controls without 
crowding or visual confusion, but otherwise as small as possible. 


Understanding AlXwindows User Help Design 


Good applications provide help facilities for the people to use when the need arises. No 
matter how intuitive you design your application to be, there will be times when some users 
get stuck. Paper documentation is important, but on-line help is often more readily available 
(manuals can easily get lost) and more appropriate. This is particularly true of 
context—sensitive help. 
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Users can call for help using the Help menu from the menu bar as described in Chapter 6. 
Since dialog boxes usually don’t have menu bars, they have a Help push button which 
opens a help window. Help windows in turn have an action bar which contains the Help 
menu. 


Types of Help 
AlXwindows provides for several types of help information. Each corresponds to an entry in 
the Help menu. If your application does not support all forms of help, be sure that your Help 
menus only include the forms you do support. 


Help On Context | 
. Context—sensitive help may be the most important type of help information for people using 
your application. Context~sensitive help describes the nature of a specific control and how 
people use that control. 


The help message is unique to the field. Context-sensitive help for a field specifying printer 
baud rate may be: 


Baud Rate is the speed at which your printer can accept data. 
Acceptable speeds are 1200, 2400, and 9600. Enter the speed in bits 
per second. 


Users request context—sensitive help from the keyboard by moving the selection cursor to 
the desired field. Pressing the Help key will then display help for that field. 


Using the mouse, people can use the On Context entry in the Help menu. The pointer 
shape changes to the help pointer shape. Selecting a field with the help pointer displays help 
on that field. After the selection, the help pointer returns to its previous shape. To cancel the 
context—-sensitive help mode, users press the Esc key. 


Typing the Help key while the Select button is pressed on a field will also display context 
heip for that field. 


Help On Window 
This help provides information about the current window. It describes the function of the 
window and the tasks that can be performed using that window. 


Users request help on the window via the Help menu. 


Help On Keys 
Applications frequently have special uses for keys, particularly function keys. Help on keys 
shows the meanings assigned by this application to special keys. 
Users fequesi neip on keys via the Help menu. 

Help Index 
Users often have a certain topic in mind when they request help. This option lists 
alphabetically a series of topics on which help is available. Users select the topics of 
interest and help on those topics is then displayed in the window. Applications may provide 
an entry field to allow users to type in a topic of interest. 


Help on Help 


This option provides information on how to use the help facility. 
Help Tutorial 


Complex applications may provide on-line help tutorials. This option provides access to 
such a capability. 
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Help On Version 
This option provides information about the specific version of the application. Information 
typically includes the name, version, and date of the application as well as copyright data. 


Help Windows 
Help windows are standard application secondary windows. They contain an action with at 
least the Help menu. Their title is the title of the window from which they were requested 
followed by the word Help. They may also have a title in the client area to specify which field 
in the window the help window describes. Place help windows so that they do not obscure 
the objects they are describing. 


Understanding International Implementation for AlXwindows 
Application Design 


Designing software for the international market requires producing applications that are 
easily translatable. In a typical scenario, when an application is translated into another 
language, some portion of it remains constant, while other portions change. 


The constant portion forms the base of the product. The base contains all parts that are 
internationally invariable. The portion that changes from country to country is the locali- 
zation portion. Identifying and separating the base from the localization portion is important 
in creating applications that are efficient to translate. 


This chapter discusses the following localization issues: 
e Collating sequences. 
e Country-specific data formats. 
e Icons and pointer shapes. 
e Scanning direction. 
e Text translation. 
e Messages. 
Collating Sequences 
To produce an alphanumeric list, printable characters are sorted according to a collating 
sequence. Printable characters include letters, numbers, punctuation characters, and other 


symbols such as asterisks (“) and ampersands (&). The collating sequence defines the value 
and position of a character relative to the other characters. 


Many applications make frequent use of collating sequences to produce alphanumeric lists. 
Examples of alphanumeric lists include the following: 


e Adirectory listing of file names. 

e The output from a sorting utility. 

e Anindex produced by a text—processing application. 

e The lists produced by a database application, such as lists of names or addresses. 


If your application contains sorting functions, it needs to be flexible enough to accommodate 
individual countryspecific collating sequences. Collating sequences must not be hard—coded 
into your application. At run—time, your application should refer to a table holding the 
collating sequences. 
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Country-Specific Data Formats 


The formats for many types of data vary from country to country. When designing data 
formats, use the same format for input and display. If the format changes, it should change 
for both. Do not make formats dependent upon other features of your application or 
dependent upon each other. 


Country—specific data includes the following: 
e Thousands separators. 
e Decimal separators. 


e Positive and negative values. 


e Currency. 


e Dates. 
e Time formats. 
e Time zones. 


e Telephone numbers. 


Thousands Separators 


For separating units of thousands, the comma, period, space, and apostrophe are 
considered to be valid separators. Your application should allow for arbitrary separators or 
no separators at all. The thousands separator should be definable by people who use your 
application or at the time of localization. 


Decimal Separators 


For separating decimal fractions, the period, comma, and the center dot are considered to 
be valid separators. Do not use the same character for both the thousands separator and 
the decimal separator. The decimal separator should be 


definable by people who use your application or at the time of localization. 


Positive and Negative Values 


Currency 


Dates 


The plus (+) and minus (—) signs are valid either before or after a number. In applications 
such as a spreadsheet, allow negative numbers to be enclosed in parentheses. 


For currency, the comma, period, and colon are valid separators. They should be modified 
independently of the separators used for other data formats. 


The currency symbol is a valid separator. It can be placed before or after the numerical 
value, or be used as the decimal separator. Allow for one or no space between the currency 
symbol and the amount. The currency symbol can be changed. 


If your application displays or prints the date, the date should be in the format and language 
of the people using your application. Properly formatting the date requires the following: 


e Alphanumeric date formats should allow sufficient storage and display space to 
accommodate date names in other languages. 


e The position of each component of an alphanumeric date should be able to be varied or 
omitted. 


e The hyphen, comma, period, space, and slash are all valid separators for the day, month, 
and year. 
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e Numeric date formats should allow the month and day fields to be reversed. For example, 
the 4th of August, 1990, can be displayed as either 4/8/90 or 8/4/90. 


e The format for entering the date should match the display format. 


Time Formats 
For time formats, hour, minute, and second components always appear in that order. Hours 
and seconds are never used without minutes. 


The colon, period, and space are valid separators for hours, minutes, and seconds. In 
24-hour notation, the four—digit format may use a separator. 


Time Zones 
For time zone displays, allow up to three characters. Also, allow for the time offsets to be 
fractions, because time offsets are not always an integer number of hours from Greenwich 
Mean Time (GMT). 


Telephone Numbers 
Telephone numbers differ in the number of digits and the format used. The space, hyphen, 
period, comma, and square brackets are all valid separators. 


For international numbers, the plus sign is frequently used in Europe to indicate that a 
number is a country code. For national numbers, it is common (but not universal) to put the 
city code or area code in parentheses. 


Icons and Pointer Shapes 
It may not always be possible to design an icon, pointer shape, or other graphical symbol 
that adequately represents the same object or function in different countries. Culture is 
inherent even in seemingly universal symbols. For example, sending and receiving mail is a 
commonly understood function, but representing that function with an icon of a mail box may 
be inappropriate because the appearance of mail boxes varies widely among countries. An 
envelope may therefore be a more appropriate icon. 


When used correctly, graphical symbols offer the following advantages: 
e They are language independent and do not need to be translated. 
e They can be used instead of computer terms that have no national-language equivalent. 


e They may.have more impact when used with text as warnings than the text alone. 


Scanning Direction 
Western languages scan left to right across the page (or display screen) and from top to 
bottom. In Eastern languages, however, this is not the case. The scanning direction of the 
country of localization may have an impact on the location of controls in dialog boxes, the 
order of selections in menus, and other areas. 


Translating Screen Text 
Well—written screen text makes an application easier for users to understand. It also makes 
translation easier. 


In particular, relationships between nouns become very explicit in other languages. You 
should avoid stringing three or more nouns together. Use prepositions to clarify the 
relationship of the nouns. 


Also, text translated from English is likely to expand 30% to 50%. If text space is limited, for 
example an error message restricted to one screen line, shorten the original version to allow 
for the translation. 
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Messages 


While common words are easy to understand and translate, jargon, when translated into 
other languages, remains jargon and serves only to confuse and intimidate people who use 
your application. Avoid using jargon whenever the jargon is not a part of the working 
vocabulary of the people using your application. 


Use the following guidelines to write screen text for translation: 
e Brief and simple sentences are easy to understand and aid in translating. 
e Affirmative statements are easier to understand than negative statements. 


e Active voice is easier for both application users and application translators to understand. 


Languages have different grammatical structures that must be accommodated when a 
product is adapted for a local environment. 


Do not build messages dynamically; that is, do not store separate subsections of a message 
and assemble them for output. This will avoid embarrassing juxtapositions of words and 
phrases. Store each message as a complete string of variable length in separate modules or 
files. Do not embed messages in your code. 


AlXwindows Application Default Keyboard and Mouse Button 


Bindings 


Different keyboards may have different numbers of keys or different key labels. Similarly, 
different mice have different numbers of buttons. Nevertheless, the AlXwindows environment 
is able to employ a standard of consistent behavior because it prescribes that the same 
function always be invoked in the same way. 


In particular, common and frequently performed functions are associated with (bound to) 
particular sequences of keyboard key presses and mouse button operations. These default 
keyboard and mouse actions, and the functions they invoke, are presented in this appendix 
in tabular form. 


Default Keyboard Assignments 
Modifier Keys 


The typical keyboard also has the following modifier keys: 
e Shift 

e Alt or Meta 

e Ctrl 


Users use these keys to modify the meanings of other keys or mouse button operations. 
Modifier keys are used in conjunction with other keys or mouse actions. Accelerators are an 
example of modifier usage. 


Keyboard Function Assignments 


The following table includes navigation, function, and special-purpose keys and their 
associated functions. 
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No Modifier [Shift [Control At 
Left Lett Range Word left 
Arrow selection 

Right Right Range Word right 

Arrow selection 

Down Range Lower window to bottom of 
Arrow selection stack.* 

Up Arrow {Up Range Raise window to top of 

selection stack.* 
Delete Delete Cut Erase to end 
of line 


Cancel Window Next Application 
menu 


Ei eeact 
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Prompt/Popup 
menu** 


Switch window 
panes 
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re 
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Minimize window* 
i sd Maximize window* 
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Pacer [| 
Page [ 
[Window ena 
ieee 


os a isl 


Switch to menu bar 


Home Beginning of line 


Soacsbar_[Selecr™ 
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Notes: 


F1 
F2 
F3 
F4 
F5 
F6 
F9 
P 
ab 






at 


Next application”” 


* An optional assignment and should remain available for user convenience. 
™ Used in substitutions when special purpose key is not available. 
*“" Provides compatibility with MS—-Windows. 
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Default Keyboard Assignments for Window Management Functions 
The following table contains the default key assignments used by the AlXwindows window 
manager for the window menu mnemonics and accelerators: 


Menu Selection and Mnemonic Accelerator 
Restore R Alt + F5 
Move M Alt + F7 
Size S Alt + F8 
Minimize n Alt + F9 
Maximize x Alt + F10 
Lower L Alt + F3 
Close C Alt + F4 


Note: Alt+F5 means to hold down the Alt key and press F5. 


Default Key Assignments for Text Keys 


The following table contains the default key assignments used by text entry boxes and other 
editing windows: 











Key Function 


[bei —‘[Dewe——SSCi CS 


Default Key Assignments for Cursor Navigation 
The following table contains the default key assignments used by the AlXwindows window 
manager for cursor navigation: 


Key Description 

Next Field Moves the cursor forward to the next field going from left to right and 
top to bottom. At the last field, the cursor wraps to the first field. 

Previous Field Moves the cursor back to the previous field going from right to left and 
bottom to top. At the first field, the cursor wraps to the last field. 

Home Moves the cursor to the beginning of the current line. 

Ctrl+Home Moves the cursor to the beginning of the data. 

End Moves the cursor to the end of the current line. 

Ctrl+End Moves the cursor to the end of the data 

Up arrow Moves the cursor to the previous choice in the client area. At the first 


choice, the cursor wraps to the last choice. 


Down arrow Moves the cursor to the next choice in the client area. At the last 
choice, the cursor wraps to the first choice. 


Right arrow Moves the cursor to the next choice. At the last choice, the cursor 
wraps to the first choice on the line below. At the bottom last choice, 
the cursor wraps to the top firs choice. 
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Left arrow Moves the cursor to the previous choice. At the first choice, the cursor 
wraps to the last choice on the line above. At the top first choice, the 
cursor wraps to the bottom last choice. 


Page Up Scrolls a window, displaying the previous page of information. 

Page Down Scrolls a window, displaying the next page of information. 

CtrltPage Up la a window, displaying information previously out of view to the 
eft. 

Ctri+Page Down Scrolls a window, displaying information previously out of view to the 
right. 

F6 Moves the cursor from one pane to another in a split window. 
Precedence is left to right, top to bottom. 

Fi0 Moves the cursor to the menu bar. 

Ctri+Left Arrow Moves the cursor to the previous word in a field. 


Ctrl+Right Arrow Moves the cursor to the next word in a field. 


Substitutions for Special Purpose Keys 
Not every keyboard contains all the special purpose keys mentioned in this style guide. 
Where a special—purpose key is available, it should be used as described. Thus keyboards 
with a Select key use it for selection. Some keyboards may not include all special-purpose 
keys. The following table presents some suggested substitutions. 


Key Substitution 
Select Spacebar or Enter 
Menu F4 

Help F4 

Alt Extend 

Esc F1i2 

Enter Return 

Next Field Tab or Ctrl+Tab 


Previous Field Shift Tab or Ctr+Shift+ Tab 


If neither a special-purpose key nor a recommended substitution is available, function key 
equivalents should be used. Applications that do not need a function key for one of the 
standard functions may use that function key for application—specific purposes. 


Operating Scroll Bars with a Mouse 
Clicking the Select button with the pointer on stepping arrows. 
Highlights the stepper arrow and moves the windowthrough the underlying 
file by a single unit, in thedirection indicated by the arrow. You must 
determine the appropriate unit to be scrolled in your application. For 
example, a unit in a spreadsheet may be a single row or column. 


Pressing the Select button with the pointer on stepper arrows. 
Highlights the stepper arrow and causes a continuous scroll, in unit steps, in 
the direction indicated by the arrow. The default step speed is approximately 
30 milliseconds and is timed by the completion of the scroll operation. 


Clicking the Select button with the pointer in the scroll region. 
Moves the window through the underlying file by one window length minus 
one unit for overlap. Clicking below (or to the right of) the slider advances to 
~- the next window's worth of information. Clicking above (or to the left of) the 
slider moves back to the previous window’s worth of information. 
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Pressing the Select button with the pointer in the scroll region. 
Continuously moves the window through the underlying file by one window 
length minus one unit for overlap until the user releases the select button or 
until the slider moves under the pointer. 


Dragging theslider with the Select button pressed. 
Moves an outline of the slider. Releasing the select button repositions the 
window to a location consistent with the new slider location. The user can 
release the select button when the pointer is anywhere in the window, not 
just within the scroll region. This action can be canceled by clicking any of 
the other buttons before releasing the select button. 


Object Selection 


Selection Task Mouse Selection 
Operation 


Change selection focus. Move the mouse to position 
the pointer 









Keyboard Selection 


Operation 









Press the navigation 
keys to position the se- 
lection cursor. 


Select a single object. Click Select [Press Select Select 


Select a range of objects. Drag Select Press Press Set 
keys 


Select all objects between Click Shift+Select Press Shift+Select 
current location and previous | © 
location. 


Select an additional object. | Click Ctri+selection operation | Press Ctrl+selection op- 
eration. 
Deselect an object. Ctrl+selection operation ona | Ctrl+selection operation 
selected object. — on a selected object. 
Incremental Text Selection 
In addition to text selection using the press—and—drag method, your application can use an 


incremental selection method. In this method, the user can perform multiple clicks of the 
select button to select successively larger (or smaller) portions of text. 
















Number of Select Button Clicks Text Block Selected 
1 click Null selection 

2 TliCKS Word 

3 clicks Line 

4 clicks Paragraph 

5 clicks Module 
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Chapter 5. Enhanced X-Windows 


Enhanced X-Windows Programming Introduction 


Enhanced X-Windows is a network-transparent windowing system that runs under the AIX 
Operating System. Enhanced X-Windows runs on systems with bitmapped display terminals. 
The X Server distributes user input to and accepts output requests from various client 
programs located either on the same system or elsewhere in a network. The Xlib library is a 
C language subroutine library that client programs use to interface with the windowing 
system. 


The application program you create is the client part of a client-server relationship; you write 
the program and the X Server provides it independence from the hardware. There is one 

X Server for each virtual terminal that runs Enhanced X-Windows. The term display refers to 
a logical virtual terminal with its associated keyboard, locator, and server unless it is 
explicitly stated otherwise. 


In Enhanced X-Windows, a window is a rectangular area on the screen that lets you view 
graphical output. Client applications can display overlapping and nested windows on one or 
more screens that are driven by X Servers on one or more systems. 


Enhanced X-Windows supports one or more screens containing overlapping windows or 
subwindows. A screen is a physical monitor, which can be color or black and white, and 
hardware. 


The windows in an X Server are arranged in a strict hierarchy. At the top of the hierarchy is 
the root window, which covers the display screen. The root window is partially or completely 
covered by child windows. All windows, except the root window, have parent windows. There 
is usually at least one window per application program. Child windows can, in tum, have 
their own child window. In this way, an application program can create a tree of arbitrary 
depth on the screen. 


i 
A child window may be larger than its parent. Part or all of the child window may extend 
beyond the boundaries of the parent. However, all output to a window is clipped by the 
boundaries of its parent window. If several children of a window have overlapping locations, 
one of the children is considered to be on top of or raised over the others, obscuring them. 
Output to areas covered by other windows is suppressed by the window system. If a window 
is obscured by a second window, the window obscures only those ancestors of the second 
window, which are also ancestors of the first window. 


A window has a border of zero or more pixels in Width, which can be any pattern or solid 
color. A window usually, but not always, has a background pattern that is repainted by the 
window system when the window is uncovered. Each window has its own coordinate 
system. Child windows obscure the parent window unless the child windows have no 
background. Graphic operations in the parent window are usually clipped by the child 
windows. 


Input from Enhanced X-Windows takes the form of events-Events may be side effects of a 
command (for example, restacking windows generates exposure events) or completely 
asynchronous (for example, the keyboard). A client program asks to be informed of events. 
Enhanced X-Windows never sends events that a program did not ask for. 


Enhanced X-Windows does not take responsibility for the contents of windows. When part or 
all of a window is hidden and then brought back onto the screen, its contents may be lost, 
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and the client program is notified by an exposure event that part or all of the window needs 
to be repainted. Programs must be prepared to regenerate the contents of windows on 
demand. 


Enhanced X-Windows also provides off-screen storage of graphics objects, called pixmaps. 
Single plane (depth 1) pixmaps are sometimes referred to as bitmaps. Bitmaps can be used 
in most graphics subroutines interchangeably with windows and are used in various graphics 
operations to define patterns, also called tiles. Windows and pixmaps together are referred 
to as drawables. 


Most of the subroutines in Xlib only add requests to an output buffer. These requests 
execute asynchronously later on the X Server, the display server. subroutines that return 
values of information stored in the server do not return; these subroutines block until an 
explicit reply is received or an error occurs. If a nonblocking call results in an error, the error 
is generally not reported by a call to an optional error handler until some later blocking call is 
made. 


If Enhanced X-Windows does not want a request to execute asynchronously, a client can 
follow the request with a call to the XSyne subroutine, which blocks until all previously 
buffered asynchronous events have been sent and acted upon. The output buffer is always 
flushed by a call to any subroutine that returns a value or waits for input (for example, the 
XPending, XNextEvent, XWindowEvent, XFiush, or XSynchronize subroutines). 


Many XIlib subroutines return an integer resource ID that allows you to refer to objects 
stored on the X Server. These objects can be of type Window, Font, Pixmap, Bitmap, 
Cursor, and GContext, as defined in the file <X11/X.h>. (The <> has the meaning defined 
by the #include statement of the C compiler and is a file relative to a well known directory. 
On the AIX Operating System this is /usr/Include.) 


Some subroutines return Status which is an integer error indication. If the subroutine fails, 
Status will be 0. If the subroutine returns a status of 0, the subroutine did not update the 
return parameters. Because C language does not provide multiple return values, many 
subroutines must return their results by writing into client-passed storage. Any pointer that is 
used to return a value is designated by the Return suffix as part of its name. All other 
pointers passed to these subroutines are used for reading only. By default, errors are 
handled either by a standard library subroutine or by a library subroutine that you provide. 
subroutines that return pointers to strings return NULL pointers if the string does not exist. 


Input events, for example, key pressed events or mouse moved events, arrive 
asynchronously from the server and are queued until they are requested by a call to the 
XNextEvent or XWindowEvent subroutines. In addition, some of the library subroutines, 
such as the XResizeWindow and XRalseWindow subroutines, generate exposure events 
or TEGuesis to repaint sections of a window that do not have valid contents. These events 
also arrive asynchronously, but the client may wish to wait for them explicitly by calling the 
XSync subroutine after calling a subroutine that may generate exposure events. 


Compiling X Programs with Enhanced X-Windows 
The following compiler command can be used to build your program: 


ce {Compiler Options} -oSample Sample.c libX11.a 


In this example, Sample.c is the name of your C language source program, Sample is the 
name of your executable C program and libX11.a is the Enhanced X-Windows subroutine 
library (/usr/lib/libX11.a). 


The compiler definitions for structures, parameters, error codes, and data types are located 
in the /usr/include/X11/Xlib.h and /usr/include/X11/X.h files. You must include these files 
in any program that uses Enhanced X-Windows subroutines. To do so, insert the following 
statement early in your program: 
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#include <X11/Xlib.h> /* also includes X11/X.h */ 

Related Information 
The <X11/X.h> header file, /usr/include/X11/Xilb.h file, /usr/include/X11/X.nh file. 
The ce Command. 


The XNextEvent subroutine, XRalseWindow subroutine, XResizeWindow subroutine, 
XSyne subroutine, XWindowEvent subroutine. 





List of Xlib Tasks 


The following is a list of the Enhanced X-Windows subroutines grouped according to the 
type of function provided. 


Opening and Closing Displays 


XOpenDisplay Open a display. 

XNoOp_=_ Execute a NoOperation protocol request. 

XFree Free in memory data created by an Xilb library subroutine. 
XCloseDisplay Close a display. 


Creating and Destroying Windows 


XCreateWindow Create unmapped subwindow. 
XCreateSimpleWindow Create unmapped InputOutput subwindow. 
XDestroyWindow Unmap and destroy window and all subwindows. 
XDestroySubwindows Destroy all subwindows of specified window. 


Manipulating Windows 


XMapWindow Map the specified window. 

XMapRalsed Map and raise the specified window. 

XMapSubwindows Map all subwindows of the specified window. 
XUnmapWindow Unmap the specified window. 

XUnmapSubwindows  Unmap all subwindows of the specified window. 
XConfigureWindow Configure the specified window. 

XMoveWindow Move the specified window. 

XResizeWindow Change the specified window’s size. 
XMoveResizeWindow Change the specified window's size and location. 
XSetWindowBorderWidth Change the border width of the window. 
XRalseWindow _ Raise the specified window. 

XLowerWindow Lower the specified window. 

XCirculateSubwindows Circulate a subwindow up or down. 
XCirculateSubwindowsUp _ Raise the lowest mapped child of window. 
XCirculateSubwindowsDown Lower the highest mapped child of window. 
XRestackWindows _ Restack a set of windows from top to bottom. 


Changing Window Attributes 


XChangeWindowaAttributes Change one or more window attributes. 
XSetWindowBackground Seta window background to a specified pixel. 
XSetWindowBackgroundPixmap Seta window background to a specified pixmap. 
XSetWindowBorder Change window's border to specified pixel. 
XSetWindowBorderPixmap Change window's border tile. 
XTranslateCoordinates Transform coordinates betweens windows. 


Obtaining Window Information 
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XQueryTree Obtain the IDs of the children and the parent windows. 
XGetWindowAttributes Get current attributes for specified window. 
XGetGeometry Get current geometry of specified drawable. 
XQueryPointer Get pointer coordinates and root window. 


Properties and Atoms 


XGetAtomName Getaname for the specified atom ID. 
XinternAtom Get an atom for the specified name. 


Manipulating Window Properties 


XChangeProperty Change the property for specified window. 
XDeleteProperty Delete a property for the specified window. 
XGetWindowProperty Get atom type and property format for window. 
XListProperties Get the specified window's property list. 
XRotateWindowProperties Rotate properties in property array. 


Setting Window Selections 


XConvertSelection Convert a selection. 
XGetSelectionOwner Get the selection owner. 
XSetSelectionOwner Set the selection owner. 


Manipulating Colormaps 


XCopyColormapAndFree Create a new colormap from specified colormap. 
XCreateColormap Create acolormap. 

XFreeColormap — Free the specified colormap. 

XQueryColor Query the RGB value for a specified pixel. 

XQueryColors Query the RGB values for array of pixels. 
XSetWindowColormap Set the colormap of the specified window. 


Manipulating Color Cells 


XAllocColor Allocate a read only color ceil. 
XAllocColorCelis Allocate read-write color cells. 
XAllocColorPlanes Allocate read/write color resources. 
XAllocNamedColor Allocate a read only color cell by name. 
XFreeColors Free colormap cells. 

XLookupColor Look up colorname. 

XStoreColor Store an RGB value into a single colormap cell. 
XStoreColors Store RGB values into colormap cells. 
XStoreNamedColor Seta pixel color to the named color. 


Creating and Freeing Pixmaps 


XCreatePixmap Create a pixmap of a specified size. 
XFreePixmap _ Free all storage associated with specified pixmap. 


Manipulating Graphics Contexts (GCs) 


XChangeGC Change the components in the specified GC. 
XCreateGC Create anew GC. 

XCopyGC Copy components from a source GC to a destination GC. 
XFreeGC Free the specified GC. 

XGContextFromGC Obtain the GContext resource ID for the GC. 
XQueryBestSize Get the best size of tile, stipple, or cursor. 
XQueryBestStipple Get the best stipple shape. 

XQueryBestTile Get the best fill tile shape. 

XSetArcMode Set the arc_mode field of the specified GC. 
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XSetBackground Set the backgound of the specified GC. 

XSetClipMask Set the clip_mask field of the specified GC to a specified pixmap. 
XSetClipOrigin Set the clip_origin field of the specified GC. 
XSetClipRectangles Set the clip_mask field of the specified GC to a list of rectangles. 
XSetDashes Set the dashed line style components of the specified GC. 
XSetFiilRule Set the fill rule of the specified GC. 

XSetFillStyle Set the fill style of the specified GC. 

XSetFont Set the current font of the specified GC. 

XSetForeground Set the foregound of the specified GC. 

XSetFunction Set display function in specified GC. 

XSetGraphicsExposures Set the graphics_exposure field of the specified GC. 
XSetLineAttributes Set the line drawing components of the GC. 
XSetPlaneMask Set the plane mask of the specified GC. 

XSetState Set foreground, background, plane mask and function in GC. 
XSetStipple Set the stipple of the specified GC. 

XSetSubwindowMode _ Set the subwindow mode of the specified GC. 
XSetTSOrigin Set the tile or stipple origin of the specified GC. 

XSetTile Set the fill tile of the specified GC. 


Clearing and Copying Areas 


XClearArea Clear a rectangular area of window. 

XClearWindow Clear the entire window. 

XCopyArea Copy drawable area between drawables of the same root and the same 
depth. 

XCopyPlane Copy single bit plane of drawable. 


Drawing Lines 


XDrawAre Draw single arc in drawable. 

XDrawArcs Draw multiple arcs in specified drawable. 

XDrawLine Draw a single line between two points in drawable. 
XDrawLines Draw multiple lines in the specified drawable. 
XDrawPoint Draw a single point in specified drawable. 
XDrawPoints Draw multiple points in specified drawable. 
XDrawRectangle Draw outline of single rectangle in drawable. 
XDrawRectangles Draw outline of multiple rectangles in drawable. 
XDrawSegments Draw multiple line segments in specified drawable. 


Filling Areas 


XFIllAre Fill single arc in drawable. 

XFillArcs _ Fill multiple arcs in drawable. 

XFillPolygon _ Fill a polygon area in drawable. 
XFiliRectangle — Fill single rectangular area in drawable. 
XFillRectangles _ Fill multiple rectangular areas in drawable. 


Loading and Freeing Fonts 


XFreeFont Unload font and free storage used by font. 
XFreeFontinfo Free the font information array. 

XFreeFontNames Free a font name array. 

XFreeFontPath Free data returned by the XGetFontPath subroutine. 
XGetFontPath Get the current font search path. 

XGetFontProperty Get the specified font property. 

XListFonts Geta list of available font names. 

XListFontsWithinfo Get names and information about loaded fonts. 
XLoadFont Load a font. 
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XLoadQueryFont Loads and queries font in one operation. 
XQueryFont Get information about a loaded font. 
XSetFontPath Set the font search path. 

XUnloadFont Unload the specified font. 


Querying Character String Sizes 


XQueryTextExtents Get 1 byte character string bounding box from server. 
XQueryTextExtents16 Get 2 byte character string bounding box from server. 
XTextExtents Get bounding box of 1 byte character string. 

XTextExtents16 Get bounding box of 2 byte character string. 

XTextWidth Get the width of an 8 bit character string. 

XTextWidthi6 Get the width of a 2 byte character string. 


Drawing Text 


XDrawimageString Draw 8 bit image text in specified drawable. 
XDrawimageString16 Draw 2 byte image text in specified drawable. 
XDrawString Draw 8 bit text in specified drawable. 

XDrawString16 Draw 2 byte text in specified drawable. 

XDrawText Draw 8 bit complex text in specified drawable. 
XDrawText16 Draw 2 byte complex text in specified drawable. 


Transferring Images 


XGetimage Getimage from rectangle in drawable. 
XGetSublmage Copy rectangle on display to image. 
XPutimage Put image from memory into rectangle in drawable. 


Manipulating Cursors 


XCreateFontCursor Create a cursor from a standard font 
XCreateGlyphCursor Create a cursor from font glyphs. 
XDefineCursor Define a cursor for a window. 
XFreeCursor Free acursor. 

XQueryBestCursor Get useful cursor sizes. 
XRecolorCursor Change the color of a cursor. 
XUndefineCursor Undefine a cursor for a window. 


Handling Window Manager Functions 


XAddToSaveSet Add a window to the client’s save-set. 
XAllowEvents Allow events to be processed after a device is frozen. 
XChangeActivePolnterGrab Change the active pointer grab. 
XChangePointerContrs! Change ine interactive feei of pointer device. 
XChangeSaveSet Add or remove a window from the client’s save-set. 
XGetinputFocus Get the current input focus. 

XGetPolnterControl Get the current pointer parameters. 
XGrabButton Grab a mouse button. 

XGrabKey Grab a single key of the keyboard. 

XGrabKeyboard Grab the keyboard. 

XGrabPointer Grab the pointer. 

XGrabServer Grab the server. 

XInstaliColormap _ Install a colormap. 

XKillClient Remove a client. 

XListInstalledColormaps Geta list of currently installed colormaps. 
XRemoveFromSaveSet Remove a window from the client's save-set. 
XReparentWindow Change the parent of a window. 
XSetCloseDownMode Change the close down mode of a client. 
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XSetinputFocus Set the input focus. 

XUngrabButton Ungrab a mouse button. 

XUngrabKey  Ungrab a key. 

XUngrabKeyboard Ungrab the keyboard. 

XUngrabPointer Ungrab the pointer. 

XUngrabServer Ungrab the server. 

XUninstaliColormap Uninstall a colormap. 

XWarpPointer Move the pointer to arbitrary point on the screen. 


Manipulating Keyboard Settings 


XAutoRepeatOff Turn off keyboard auto-repeat. 

XAutoRepeatOn — Turn on keyboard auto-repeat. 

XBell Set the volume of the bell. 

XChangeKeyboardControl Change keyboard settings. 
XChangeKeyboardMapping Change the mapping of symbols to keycodes. 
XDeleteModifiermapEntry Delete an entry for XModiflerKeymap structure. 
XDisplayKeycodes Return minimum and maximum number of keycodes supported by 
the specified display. 

XFreeModifiermap Free XModiflerKeymap structure. 
XGetKeyboardControl Get the current keyboard settings. 
XGetKeyboardMapping Get the mapping of symbols to keycodes. 
XGetModiflerMapping Get keycodes to be modifiers. 
XGetPolinterMapping Get the mapping of buttons on the pointer. 
XInsertModifiermapEntry Add an entry from XModiflerKeymap structure. 
XNewModiflermap Create the XModifierKeymap structure. 
XQueryKeymap _ Get the state of the keyboard keys. 

XSetModifierMapping Set keycodes to be modifiers. 

XSetPointerMapping Set the mapping of buttons on the pointer. 


Controlling the Screen Saver 


XActivateScreenSaver Activate the screen saver. 
XForceScreenSaver Turn the screen saver on or off. 
XGetScreenSaver Get the current screen saver settings. 
XSetScreenSaver Set the screen saver. 


Manipulating Hosts and Access Control 


XAddHost Adda host. 

XAddHosts Add multiple hosts. 
XDisableAccessControl Disable access control. 
XEnableAccessControl Enable access control. 
XListHosts Get the list of hosts. 

XRemoveHost Remove a host. 

XRemoveHosts Remove multiple hosts. 
XSetAccessControl Change access control. 


Handling Events 


XCheckifEvent Check event queue for specified event without blocking. 
XCheckMaskEvent Remove the next event that matches a specified mask without 
blocking. 

XCheckTypedEvent Get the next event that matches event type. 
XCheckTypedWindowEvent Get the next event for specified window. 
XCheckWindowEvent Remove next event that matches the specified window and 
mask without blocking. 

XDisplayMotionBufferSize Return the size of the motion buffer. 
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XEventsQueued Check the number of events in the event queue. 
XFlush Flush the output buffer. 

XGetMotionEvents Get the motion history for specified window. 
XlfEvent Check event queue for specified event and remove it. 
XMaskEvent Remove the next event that matches a specified mask. 
XNextEvent Get the next event and remove it from the queue. 
XPeekEvent Peek at the event queue. 

XPeekifEvent Check event queue for specified event. 

XPending Return the number of events that are pending. 
XPutBackEvent Push event back to top of event queue. 

XSelectinput Select events to be reported to the client. 

XSendEvent Send an event to a specified window. - 

XSyne__—- Flush the output buffer and wait until all requests are completed. 
XWindowEvent Remove next event that matches the specified window and mask. 


Enabling or Disabling Synchroniztion 


XSetAfterFunction Set the previous after function. 
XSynchronize Enable or disable synchronization. 


Using Default Error Handling 


XDisplayName Get name of display currently being used. 
XGetErrorDatabaseText Get error text from the error database. 
XGetErrorText Get error text for specified error code. 
XSetErrorHandler Set error handler. 

XSetlOErrorHandler Set error handler for fatal I/O errors. 


Communicating with Window Managers 


XFetchName Get the name of a window. 

XGetClassHint Get the class of a window. 

XGeticonName Get the name of an icon window. 

XGeticonSizes Get the values of icon size atom. 

XGetNormalHints Get size hints for window in normal state. 
XGetSizeHints Get the values of type WM_SIZE_HINTS properties. 
XGetStandardColormap Get colormap associated with specified atom. 
XGetTransientForHint Get WM_TRANSIENT_FOR property for window. 
XGetWMHints Get the value of the window manager’s hints atom 
XGetZoomhHints Get values of the zoom hints atom. 

XSetClassHint Set the class of a window. 

XSetCommand — Set the value of the command atom. 

XSeticonName = Assign a name tc an icon window. 

XSeticonSizes Set the values of icon size atom. 

XSetNormalHints Set size hints for window in normal state. 
XSetSizeHints Set the values of typeWM_SIZE_HINTS properties. 
XSetStandardColormap Set colormap associated with specified atom. 
XSetStandardProperties Specify a minumum set of properties. 
XSetTransientForHint Set WM_TRANSIENT_FOR property for window. 
XSetWMHints Set the value of the window manager's hints atom. 
XSetZoomHints Set values of the zoom hints atom. 

XStoreName Assign aname to a window. 


Keyboard Event Functions 


XKeycodeToKeysym Convert keycode to a keysym value. 
XKeysymToKeycode Convert keysym value to keycode. 
XKeysymToString Convert keysym value to keysym name. 
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XLookupKeysym Translate keyboard event into keysym value. 
XLookupMapping Get mapping of keyboard event from keymap file. 
XLookupString __ Translate keyboard event into character string. 

XRebindCode Change the keyboard mapping in keymap file. 
XRebindKeysym Map character string to specified keysym and modifiers. 
XRefreshKeyboardMapping Refresh stored modifier and keymap information. 
XStringToKeysym Convert keysym name to keysym value. 

XUseKeymap Change keymap files. 


Handling Default Geometry Color 


XGeometry Parse the window geometry, given the padding and font values. 
XGetDefault Get default window options. 

XParseColor Obtain the RGB values from the color name. 

XParseGeometry Parse standard window geometry options. 
XResourceManagerString Return the RESOURCE_MANAGER property from the 
screen of the root window of screen 0. 


Manipulating Regions 


XClipBox Generate the smallest enclosing rectangle in region. 
XCreateRegion Create anew empty region. 

XDestroyRegion Free storage associated with specified region. 
XEmptyRegion Determine if specified region is empty. 
XEqualRegion Determine if two regions are the same. 
XintersectRegion Compute intersection of two regions. 
XOffsetRegion Move specified region by specified amount. 
XPointinRegion Determine if point lies in specified region. 
XPolygonRegion Generate a region from points. 

XRectinRegion Determine if rectangle lies in specified region. 
XSetRegion Set the GC to the specified region. 

XShrinkReglon Reduce specified region by specified amount. 
XSubtractRegion Subtract two regions. 

XUnionRectWithRegion Create a union of source region and rectangle. 
XUnionReglon Compute union of two regions. 

XXorRegion Get difference between union and intersection of regions. 


Using Cut and Paste Buffers 


XFetchBuffer Get data from specified cut buffer. 
XFetchBytes Get data from first cut buffer. 
XRotateBuffers Rotate the cut buffers. 
XStoreBuffer Store data in specified cut buffer. 
XStoreBytes Store data in first cut buffer. 


Querying Visual Types 


XGetVisualinfo Get list of visual information structures. 
XMatchVisualinfo Get visual information matching screen depth and class. 
XVisualIDFromVisual Return the visual ID for the specified visual type. 


Manipulating Images 


XAddPixel Increment each pixel in pixmap by constant value. 
XCreatelmage Allocate memory for Ximage structure. 
XDestroylmage Free memory for Ximage structure. 

XGetPixel Geta pixel value in an image. 

XPutPixel Seta pixel value in an image. 

XSublmage Create image that is subsection of specified image. 
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Manipulating Bitmaps 


XCreateBitmapFromData _ Include bitmap in C program. 
XCreatePixmapFromBitmapData Create pixmap using bitmap data. 
XReadBitmapFile Read in a bitmap from a file. 

XWriteBitmapFile Write out a bitmap to a file. 


Using the Resource Manager 


Xpermalioc Allocate memory which is never freed. 
XrmGetFileDatabase Create a database from specified file. 
XrmGetResource Retrieve a resource from a database. 
XrmGetStringDatabase Create a database from specified string. 
Xrminitialize —_ Initialize the resource manager. 

XrmMergeDatabases Merge two databases. 

XrmParseCommand Store command options into a database. 
XrmPutFileDatabase Copy database into specified file. 
XrmPutLineResource Store single resource entry into database. 
XrmPutResource Store resource into database. 
XrmPutStringResource Store string resource into database. 
XrmQGetResource __ Retrieve a quark from a database. 
XrmQGetSearchList Geta resource search list of database levels. 
XrmQGetSearchResource Geta quark search list of database levels. 
XrmQPutResource = Store binding and quarks into database. 
XrmQPutStringResource Store string binding and quarks into database. 
XrmQuarkToString Convert a quark to a character string. 
XrmStringToBindingQuarkList Convert strings to bindings and quarks. 
XrmStringToQuark Convert character string to a quark. 
XrmStringToQuarkList Convert character strings to quark list. 
XrmUniqueQuark Allocate a new quark. 


Using the Context Manager 


XDeleteContext Delete data associated with window and context type. 
XFindContext Get data associated with window and context type. 
XSaveContext Store data associated with window and context type. 
XUniqueContext Allocate a new context. 


Enhanced X-Windows Display Subroutines Overview 


Before a program can use a display, the program must establish a connection to the 

X Server driving the display. Once you have established a connection, you can then use the 
Xlib macros and functions to return information about this display such as image format size 
and depth. 


Opening an Enhanced X-Windows Display 
To open a connection to the X Server controlling a specified display, use the XOpenDisplay 
subroutine. This subroutine returns a display structure that serves as the connection to the 
X Server. This display structure contains information about the X Server and connects the 
specified hardware display to the server through TCP or UNIX domain sockets. If the 
Hostname is a host system name and a colon (:) separates the host name and display 
number, the XOpenDisplay subroutine connects the host and the display using TCP 
sockets. If the Hostname does not exist or is unIx and a colon (:) separates it from the 
display number, the XOpenDisplay subroutine connects the host and the display using 
UNIX domain sockets. 
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A single server can support any or all of these transport mechanisms simultaneously. 
The display name or DISPLAY environment variable is a string that has the format: 
Hostname: Number.Screen 


Hostname Specifies the name of the host system where the display is physically 
attached. The Hostname should be followed by a colon (:). 


Number Specifies the ID number of the display server on that host machine. The | 
display number can be followed by a period (.). 


Screen Specifies the number of the screen on that host server. Multiple screens can 
be connected to or controlled by a single X Server. The screen sets an 
internal variable that can be accessed with the DefaultScreen macro or the 
XDefaultScreen subroutine. 


For example, the following would specify screen 0 display 2 on the system named Dave: 
Dave:2.0 


Applications should not directly modify any part of the Display and Screen data structures. 
These structures should be considered read-only by the user, but they can be changed by 
some subroutines or display macros. 


Closing an Enhanced X-Windows Display 
When the X Server connection to a client is closed, either by an explicit call to the 
XCloseDisplay subroutine or by a process that exits, the X Server performs the following 
operations automatically: 


e Disowns all selections owned by the client. 


e Performs the XUngrabPointer and XUngrabKeyboard subroutines if the client 
application has actively grabbed the pointer or the keyboard. 


e Performs the XUngrabServer subroutine if the client has grabbed the server. 
e Releases all passive grabs made by the client application. 


¢ Marks all resources (including colormap entries) allocated by the client application as 
permanent or temporary, depending on whether the close-down mode is the value of 
RetainPermanent or RetainTemporary. However, this does not prevent other client 
applications from explicitly destroying the resources. 


When the X Server connection to a client is closed in the DestroyAll mode, the X Server 
destroys all of the resources of the client application as follows: 


e Examines each window in the client save set to determine if the save set window is an 
inferior or subwindow of a window created by the client. (The save set is a list of other 
client windows that are referred to as save set windows.) If so, the X Server reparents 
the save set window to the closest ancestor so that the save set window is not an inferior 
of a window created by the client. The reparenting leaves unchanged the absolute 
coordinates (with respect to the root window) of the upper-left outer corner of the save-set 
window. 


e Performs a MapWindow request on the save set window if the save set window is 
unmapped. The X Server performs a MapWindow request even if the save set window is 
not an inferior of a window created by the client. 


e Examines each window in the client save set and destroys all windows created by the 
client. 
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e Performs the appropriate free request on each non-window resource created by the client 
in the server (for example, Font, Pixmap, Cursor, Colormap, and GContext). 


e Frees all colors and colormap entries allocated by a client application. 


Additional processing occurs when the last connection to the X Server closes. An X Server 
goes through a cycle of having no connections and having some connections. When the last 
display connection to the X Server closes as a result of a connection closing with the 
DestroyAll close—mode, the X Server: 


e Resets its state, as if it had just been started. The X Server begins by destroying all 
lingering resources from clients that were terminated in RetainPermanent or 
RetainTemporary mode. 


e Deletes all but the predefined atom identifiers. 
e Deletes all properties on all root windows. 


e Resets all device maps and attributes (for example, key click, bell volume, and 
acceleration) and the access control list. 


e Restores the standard root tiles and cursors. 
e Restores the default font path. 
e Restores the input focus to state PolnterRoot. 


However, the X Server does not reset if a connection with a close-mode is set to 
RetainPermanent or RetainTemporary. 


Related Information 
The DisplayCells macro, DisplayHelght macro, DisplayHelghtMM macro, 
DisplayOfScreen macro, DisplayPlanes macro, DisplayString macro, DisplayWidth 
macro, DisplayWidthMM macro, DefaultScreen macro. 


The XCloseDisplay subroutine, XFree subroutine, XNoOp subroutine, XOpenDisplay 
subroutine, XSetCloseDownMode subroutine, XSetSelectlonOwner subroutine, 
XUngrabPointer subroutine, XUngrabKeyboard subroutine, XUngrabServer subroutine. 


Enhanced X-Windows Events and Event-Handling Subroutines 
Overview 


Most applications simply are event loops. That is, they wait for an event. decide what to do 
with it, execute some amount of code, which, in turn, results in changes to the display, and 
then wait for the next event. An event is data generated asynchronously by the X Server as 
a result of some device activity or as side effects of a request sent by an XIlb library 
subroutine. 


A client application communicates with the X Server through the connection established with 
the XOpenDisplay subroutine. A client application sends requests to the X Server through 
this connection. These requests are made by the Xllib library subroutines that are called by 
the client applications. The X Server sends replies or events back to the client application. 
Most requests made by the Xlib library subroutines do not generate replies. Other requests 
generate multiple replies. Numerous XIib library subroutines cause the X Server to generate 
events. In addition, typing or moving the pointer can generate events asynchronously. 
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Using Enhanced X-Windows to Define Event Types 
An event type describes a specific event generated by the X Server. For each event type, 
there is a corresponding constant name defined in the <X11/X.h> file. When referring to the 
event types, use the constant name defined in this file. Grouping one or more event types 
into logical categories is often useful. For example, exposure processing refers to the 
processing that occurs for the exposure events Expose, GraphicsExpose, and NoExpose. 


Device-related events propagate from the source window to ancestor windows until some 
client application has selected that event type or until the event is explicitly discarded. The 
X Server sends an event to a client application only when the client application specifically 
asked to be informed of that event type, usually by calling the XSelectinput subroutine. 
However, KeymapNotify events are always sent. 


The following table lists the event categories and their associated event types. 


1 
(3 
(a 
ee 
frst 


Exposure events Expose 
GraphicsExpose 
NoExpose 


CirculateRequest 
ConfigureRequest 
MapRequest 

ResizeRequest 


CirculateNotify 
ConfigureNotify 
CreateNotify 
DestroyNotify 
GravityNotify 
MapNotify 
MappingNotify 
ReparentNotify 
UnmapNotify 
Visibility Notify 


Colormap state notification event ColormapNotify 



























Structure control events 














Window state notification events 
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Client communication events ClientMessage 
PropertyNotify 
SelectionClear 
SelectionNotify 
SelectionRequest 


Lpfk events LPFKeyPress 


Focus and mapping change events | AlXFocusIn 
AlXFocusOut 
AlXDeviceMappingNotify 





Using Enhanced X-Windows to Define Event Structures 
Each event type has a corresponding structure declared in the <X11/Xlib.h> header file. All 
event structures have the common fields found in the XAnyEvent data structure. 


The X Server may send events at any time in the input stream, even during the time the 
client application sends a request and receives a reply. The Xllb library stores, in an event 
queue for later use, any events received while waiting for a reply. It provides several 
subroutines that check events in the event queue. 


In addition to the individual structures declared for each event type, there is also an XEvent 
structure. The XEvent structure is a union of the individual structures declared for each 
event type. After you determine the event type, use the structures declared in the 
<X11/Xlib.h> header file when referring to it in a client application. Depending on the type 
field of the event, you should access elements of each event by using the XEvent structure. 


Using Enhanced X-Windows to Define Event Masks 
The event mask describes the event or events to be returned to the client application by the 
X Server. Client applications select event reporting of most events relative to a window. An 
event mask is passed in the EventMask parameter to an Xllb library event-handling 
subroutine. The event masks are in the <X11/X.hs> file. 


Most events are not reported to clients when they are generated unless the client has 
specifically asked for them. However, GraphicSExpose and NoExpose events are reported 
by default as a result of XCopyPlane and XCopyArea subroutines, unless the client 
suppresses them by setting the graphics_exposures field in the GC to the value of False. 
SelectionClear, SelectionRequest, SelectionNotify or CilentMessage events cannot be 
masked, but generally are sent only to clients cooperating with selections. A MappingNotify 
EVEii iS always Seni to ciienis when the keyboard mapping is changed. 

The following table lists the event mask constants passed in the EventMask parameter and 
the circumstances in which the event mask is used. 


Event Mask Circumstances 

NoEventMask No events wanted 

KeyPressMask Keyboard down events wanted 
KeyReleaseMask Keyboard up events wanted 
ButtonPressMask Pointer button down events wanted 
ButtonReleaseMask Pointer button up events wanted 
EnterWindowMask Pointer window entry events wanted 
LeaveWindowMask Pointer window leave events wanted 
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PointerMotionMask 
PointerMotionHintMask 
Button1MotionMask 
Button2MotionMask 
Button3MotlonMask 
Button4MotionMask 
Button5MotionMask 
ButtonMotionMask 
KeymapStateMask 
ExposureMask 
VisibilityChangeMask 
StructureNotifyMask 
ResizeRedirectMask 
SubstructureNotifyMask 
SubstructureRedirectMask 
FocusChangeMask 
PropertyChangeMask 
ColormapChangeMask 
OwnerGrabButtonMask 


DialRotateMask 

LPF KeyPressMask 
AlXDeviceMapChangeMask 
AlXFocusChangeMask 


Pointer motion events wanted 

Pointer motion hints wanted 

Pointer motion while button 1 down 
Pointer motion while button 2 down 
Pointer motion while button 3 down 
Pointer motion while button 4 down 
Pointer motion while button 5 down 
Pointer motion while any button down 
Any keyboard state change wanted 
Any exposure wanted 

Any change in visibility wanted 

Any change in window structure wanted 
Redirect resize of this window 
Substructure notification wanted 
Redirect substructure of window 

Any change in input focus wanted 
Any change in property wanted 

Any change in Colormap wanted 


Automatic grabs should activate when the OwnerEvents 
parameter of the specific grab subroutine is the value of 
True 


Dial rotate events wanted 

Lpfk key-down events wanted 

Device state change events wanted 
Dial or Ipfk input focus events wanted 


Using Enhanced X-Windows to Process Events 


The event types reported to a client application during event processing depend on which 
event masks are passed to the EventMask parameter of the XSelectinput subroutine. Some 
event masks have a one-to-one correspondence between the event mask constant and the 
event type constant. For example, if the event mask ButtonPressMask is passed, the 

X Server sends back only ButtonPress events. Most events contain a time field that 
indicates the time at which an event occurred. 


In other cases, one event mask constant can map to several event type constants. For 

example, if the event mask SubstructureNotifyMask is passed, the X Server can send 
back CirculateNotify, ConfigureNotify, CreateNotify, DestroyNotify, GravityNotity, 

MapNotify, ReparentNotify, or UnmapNotify events. 


In another case, two event mask constants map to one event type constant. For example, if 
the event mask PointerMotionMask or PointerMotionHintMask is passed, the X Server 
sends back a MotionNotify event. 


Chapter 5. Enhanced X-Windows. 5-15 


The following table lists the event mask, the associated event type and the structure name 
associated with the event type. (NA appears in columns for which the information is not 
applicable.) 


[Eventask [Event type____—([ata Structure 































StructureNotifyMask CirculateNotify XCirculateEvent 


StructureNotifyMask ConfigureNotify XConfigureEvent 















[SrucureNotiyiask | MapNotly | XWapvent_—__——_—| 


SubstructureNotifyMask DestroyNotify XDestroyWindowEvent 
SubstructureNotifyMask GravityNotify XGravityEvent 
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Using Enhanced X-Windows to Process Specific Pointer Button Events 


When a pointer button is pressed with the pointer in a window and no active pointer grab is 
in progress, the X Server searches the ancestors of the specified window, from the root 
down, for a passive grab to activate. If there is no matching passive grab on the button, the 
X Server automatically starts an active grab for the client receiving the event and sets the 
last-pointer-grab time to the current server time. The effect is equivalent to the 
XGrabButton subroutine with the following client parameters: 


window The event window. 

event. mask The selected pointer-motion events of the client on the 
event window. 

pointer_mode GrabModeAsync. 

keyboard_mode GrabModeAsync. 

owner_events The value of True, if the client selected 


OwnerGrabButtonMask on the event window. Otherwise, 
it is the value of False. 


confine_to None. 
cursor None. 


The grab is automatically terminated when all buttons are released. Clients can modify the 
active grab by calling the XUngrabPointer and XChangeActivePointerGrab subroutines. 


Using Enhanced X-Windows to Process Common Keyboard and Pointer 


Events 


The X Server can report KeyPress and KeyRelease events to clients requesting information 
about when a key is pressed or released. The X Server generates these events whenever a 
key changes state, that is, whenever a key is pressed or released. These events are 
generated for all keys, even keys mapped to modifier bits. 
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The X Server reports ButtonPress and ButtonRelease events to clients requesting 
information about when a pointer button is pressed or released. The X Server generates 
these events whenever a pointer button changes state, that is, whenever a pointer button is 
pressed or released. 


The X Server reports MotionNotify events to clients requesting information about when the 
pointer moves. The X Server generates this event whenever the pointer changes state, that 
is, whenever the pointer is moved and the pointer motion begins and ends in the window. 
The granularity of MotlonNotify events is not guaranteed, but a client that selects this. event 
type is guaranteed to receive at least one event when the pointer moves and then rests. 


To receive the KeyPress, KeyRelease, ButtonPress, and ButtonRelease events in a client 
application, you pass a window ID and KeyPressMask, KeyReleaseMask, 
ButtonPressMask, and ButtonReleaseMask as the EventMask parameter to the 
XSelectinput subroutine. 


To receive MotionNotify events in a client application, pass a window ID and one or more of 
the following event masks as the EventMask parameter to the XSelectInput subroutine: 


Button1 MotionMask-Button5MotionMask 
The client application receives MotionNotify events only 
when one or more of the specified buttons is pressed. 


ButtonMotionMask The client application receives MotionNotify events only 
when at least one button is pressed. 


PointerMotionMask The client application receives MotionNotify events 
independent of the state of the pointer buttons. 
PointerMotionHintMask The X Server is free to send only one MotionNotify event 


(with the is_hint field of the XPointerMovedEvent structure 
set to NotifyHint) to the client for the event window, until 
either the key or button state changes, or the pointer leaves 
the event window, or the client calls the XQueryPointer or 
XGetMotionEvents subroutines. 


The source of the input event is the smallest window containing the pointer. The window 
used by the X Server to report these events depends on its position in the window hierarchy 
and whether any intervening window prohibits the generation of these events. The X Server 
searches up the window hierarchy, starting with the source window until it locates the first 
window specified by a client as having an interest in these events. If one of the intervening 
windows has its do_not_propagate_mask field set to prohibit generation of the event type, 
the event of those types will be suppressed. Clients can modify the actual window used for 
reporting by penorming active grabs and, in ine case of keyboard events, by using the focus 
window. The window in which the event is reported is the event window. 


Using Enhanced X-Windows for Keyboard Event Subroutines 
The Xlib library provides subroutines to manipulate keyboard events or to determine 
information about a key symbol. These subroutines include keyboard event subroutines. 


The X Server does not predefine the keyboard to be ASCII characters. Knowing that the “a” 
key was just pressed or possibly that it was just released is often useful. When a key is 
pressed or released, the X Server sends keyboard events to client programs. The structures 
associated with keyboard events contain a keycode field that assigns a number to each 
physical key on the keyboard. 


Because keycodes are arbitrary and may differ from server to server, client programs 
dealing with ASCII text, for example, must explicitly convert the keycode value into ASCII. 
The transformation of keycodes to ASCII or other character sets is arbitrary. Keyboards 
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often differ and writing code that assumes the existence of a particular key on the main 
keyboard can create portability problems. It can also be difficult to receive KeyRelease 
events on certain X Server implementations because of hardware or software restrictions. 
Therefore, the Xllb library provides subroutines to customize the keyboard layout. 


Keyboard events are usually sent to the smallest enclosing window that is interested in that 
type of event undemeath the pointer position. It is also possible to assign the keyboard input 
focus to a specific window. When the input focus is attached to a window, keyboard events 
go to the client that selects input on that window rather than to the window under the pointer. 


Some implementations cannot support KeyRelease events. While some applications exploit 
KeyRelease events to provide superior user interfaces, portability should be considered in 
designing software that uses KeyRelease events or changes key assignments. For 
example, it is possible to guarantee the existence of the a-z, spacebar, and carriage return 
keys, but not all keys on all keyboards. 


Using Enhanced X-Windows Window Crossing Events 
This section describes the processing that occurs for the window crossing events. If a 
pointer motion or a window hierarchy change causes the pointer to be in a different window 
than before, the X Server reports EnterNotify or LeaveNotify events to clients that have 
selected these events. 


EnterNotify and LeaveNotify events caused by a hierarchy change are generated after any 
hierarchy event, UnmapNotify, MapNotify, ConfigureNotify, GravityNotlfy, 
CirculateNotlify, caused by that change; but the ordering of EnterNotify and LeaveNotity 
events with respect to FocusOut, VisibilltyNotify, and Expose events is not constrained by 
the X protocol. 


This type of processing contrasts with MotionNotify events, which are also generated when 
the pointer moves, but the pointer motion begins and ends in a single window. An 
EnterNotify or LeaveNotify event can also be generated when a client application calls the 
XGrabPointer and XUngrabPointer subroutines. 


To receive EnterNotify events, pass a window ID and EnterWindowMask as the 
EventMask parameter to XSelectinput subroutine. 


To receive LeaveNotify events, pass the window ID and LeaveWindowMask as the 
EventMask parameter to the XSelectinput subroutine. 


Using Enhanced X-Windows to Process Normal Entry or Exit Events 
The EnterNotify and LeaveNotify events are generated when the pointer moves from one 
window to another window. Normal events are identified by the XCrossingEvent data 
structure, which is the structure for both the XEnterWindowEvent, or 
XLeaveWindowEvent data structures with the mode field set to NotifyNormal. 


e When the pointer moves from window A to window B, and window A is an inferior of 
window B, the X Server generates: 


— ALeaveNotify event on window A that has the XLeaveWindowEvent data structure 
with NotifyAncestor as the deiail field. 


— ALeaveNotify event on each window between window A and window B exclusive, that 
has the XLeaveWindowEvent data structure with NotifyVirtual as the detail field. 


- An EnterNotify event on window B that has the XEnterWindowEvent data structure 
with Notifyinferior as the detail field. 


e When the pointer moves from window A to window B, and window B is an inferior of 
window A, the X Server generates: 
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~ A LeaveNotify event on window A that has the XLeaveWindowEvent data structure 
with Notifyinferior as the detail field. 


— An EnterNotify event on each window between window A and window B exclusive, 
that has the XEnterWindowEvent data structure with NotifyVirtual as the detail field. 


~ An EnterNotify event on window B that has the XEnterWindowEvent data structure 
with NotifyAncestor as the detail field. 


e When the pointer moves from window A to window B, and window C is their least 
common ancestor, the X Server generates: 


— ALeaveNotify event on window A that has the XLeaveWindowEvent data structure 
with NotifyNonlinear as the detail field. 


— ALeaveNotify event on each window between window A and window C exclusive, that 
has the XLeaveWindowEvent data structure with NotifyNonlinearVirtual as the 
detail field. 


— An EnterNotify event on each window between window C and window B exclusive, 
that has the XEnterWindowEvent data structure with NotifyNonlinearVirtual as the 
detail field. 


— An EnterNotify event on window B that has the XEnterWindowEvent data structure 
with NotifyNonlinear as the detail field. 


e When the pointer moves from window A to window B on different screens, the X Server 
generates: 


— ALeaveNotify event on window A that has the XLeaveWindowEvent data structure 
with NotifyNonlinear as the detail field. 


— If window A is not a root window, the X Server generates a LeaveNotify event on each 
window above window A, up to and including its root window, that has the 
XLeaveWindowEvent data structure with NotifyNonlinearVirtual as the detail field. 


~ If window B is not a root window, the X Server generates an EnterNotify event on 
each window from the root of window B, down to but not including window B, that has 
the XEnterWindowEvent data structure with NotifyNonlinearVirtual as the detail 
field. 


— An EnterNotify event on window B that has the XEnterWindowEvent data structure 
with the NotifyNonlinear as the detail field. 


Using Enhanced X-Windows to Process Grab and Ungrab Entry or Eyit 

Events 
Pseudo-motion mode EnterNotify and LeaveNotify events are generated when a pointer 
grab activates or deactivates. Events in which the pointer grab activates are identified by the 
XEnterWindowEvent or XLeaveWindowEvent data structures with the mode field set to 
NotifyGrab. Events in which the pointer grab deactivates are identified by the 
XEnterWindowEvent or XLeaveWindowEvent data structures with the mode field set to 
NotifyUngrab. 


When a pointer grab activates after any initial warp into a confine_to window, and before 
generating any actual ButtonPress event that activates the grab, G is the grab_window for 
the grab, and P is the window the pointer is in, the X Server does the following: 


e It generates the EnterNotify and LeaveNotify events with the mode fields of the 
XEnterWindowEvent and XLeaveWindowEvent data structures set to NotifyGrab. 
These events are generater as if the pointer warped suddenly from its current position in 
P (the window the pointer is in) to some position in G (the grab_window for the grab). 
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However, the pointer does not warp, and the X Server uses the pointer position as the 
initial and final positions for the events. 


When a pointer grab deactivates after generating any actual ButtonRelease event that 
deactivates the grab, the G is the grab_window for the grab, and P is the window the pointer 
is in, the X Server does the following: 


e It generates the EnterNotify and LeaveNotify events with the mode fields of the 
XEnterWindowEvent and XLeaveWindowEvent data structures set to NotifyUngrab. 
These events are generater as if the pointer warped suddenly from its current position in 
P (the window the pointer is in) to some position in G (the grab_window for the grab). 
However, the pointer does not warp, and the X Server uses the pointer position as the 
initial and final positions for the events. 


Using Enhanced X-Windows to Process Input Focus Events 
The X Server reports Focusin or FocusOut events to client applications requesting 
information about changes to Input focus or focus window. The input focus or focus 
window is the point or window at which the keyboard is attached and input is received. The 
focus window can be the root window or a top-level window. The focus window and the 
position of the pointer determines which window receives keyboard input. Clients may need 
to know when the focus window changes. Input focus or the focus window changes when a 
client application uses the XGrabKeyboard or XUngrabKeyboard subroutines. 


To receive Focusin and FocusOut events in a client application, pass a window ID and 
FocusChangeMask as the EventMask parameter to the XSelectinput subroutine. 


The XFocusChangeEvent data structure is the data structure for both XFocusinEvent and 
XFocusOutEvent. 


All FocusOut events caused by a window unmap are generated after any UnmapNotify 
event, but the ordering of FocusOut events with respect to generated EnterNotify, 
LeaveNotify, VisibilityNotify, and Expose events is not constrained by the X protocol. 


Using Enhanced X-Windows to Process Normal Focus Events and 
Focus Events While Grabbed 
Normal focus events are identified by the XFocusinEvent or XFocusOutEvent data 
structures with NotifyNormal as the mode field. Focus events while grabbed are identified 
by XFocusinEvent or XFocusOutEvent data structures with NotifyWhileGrabbed as the 
mode field. The X Server processes normal focus events and while grabbed focus events 
according to the following focus scenarios: 


e When the focus moves from window A to window B, window A is an inferior of window B 
and the pointer in window P, the X Server does the following: 


— It generates a FocusOut event on window A, with the detail field of the 
XFocusOutEvent data structure set to the value of NotifyAncestor. 


— It generates a FocusOut event on each window between window A and window B 
exclusive, with the detail field of the XFocusOutEvent data structure set to the value 
of NotifyVirtual. 


— It generates a Focusin event on window B, with the detail field of the 
XFocusOutEvent data structure set to the value of Notifyinferior. 


— If window P is an inferior of window B, but window P is not window A or an inferior or 
ancestor of window A, the X Server generates a Focusin event on each window below 
window B, down to and including, window P, with the detail field of the XFocusinEvent 
data structure set to the value of NotifyPointer. 
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e When the focus moves from window A to window B, and window is an inferior window of 
window A with the pointer in window P, the X Server generates: 


— If window P is an inferior of window A, but window P is not window A or an inferior 
window of window B or an ancestor of window B, the X Server generates a FocusOut 
event on each window from window P up to, but not including, window A (in that order), 
that has the XFocusOutEvent data structure with NotifyPointer as the detail field. 


— A FocusOut event on window A that has the XFocusOutEvent data structure with 
Notifyinferior as the detail field. 


- A Focusin event on each window between window A and window B exclusive, that has 
the XFocusinEvent data structure with NotifyVirtual as the detail field. 


-— A Focusin event on window B that has the XFocusInEvent data structure with 
NotifyAncestor as the detail field. 


e When the pointer moves from window A to window B, and window C is their least 
common ancestor, and the pointer is in window P, the X Server generates: 


— If window P is an inferior of window A, the X Server generates a FocusOut event on 
each window from window P up to, but not including, window A, that has the 
XFocusOutEvent data structure with NotifyPointer as the detail field. 


-~ A FocusOut event on window A that has the XFocusOutEvent data structure with 
NotifyNonlinear as the detail field. 


— A FocusOut event on each window between window A and window C exclusive that 
has the XFocusOutEvent data structure with NotifyNonlinearVirtual as the detail 
field. 


— A Focuslin event on each window between window C and window B exclusive that has 
the XFocusinEvent data structure with NotifyNonlinearVirtual as the detail field. 


— A Focusin event on window B that has the XFocusinEvent data structure with 
NotifyNonlinear as the detail field. 


— If window P is an inferior of window B, the X Server generates a Focusin event on 
each window below window B down to, and including, window P, that has the 
XFocusinEvent data structure with NotifyPointer as the detail field. 


e When the focus moves from window A to window B on different screens with the pointer in 
window P, the X Server generates: 


— If window P is an inferior of window A, the X Server generates a FocusOut event on 
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each window from window P up to, but not inciuding, window A, that has tne 


XFocusOutEvent data structure with NotifyPointer as the detail field. 


~ A FocusOut event on window A that has the XFocusOutEvent data structure with 
NotifyNonlinear as the detail field. 


~ If window A is not a root window, the X Server generates a FocusOut event on each 
window above window A, up to and including its root window, that has the 
XFocusOutEvent data structure with NotifyNonlinearVirtual as the detail field. 


— If window B is not a root window, the X Server generates a Focusin event on each 
window from the root of window B down to, but not including, window B, that has the 
XFocus!nEvent data structure with NotifyNonlinearVirtual as the detail field. 


— A Focusin event on window B that has the XFocusinEvent data structure with 
NotifyNonlinear as the detail field. 
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— If window P is an inferior of window B, the X Server generates a Focusin event on 
each window below window B down to, and including, window P that has the 
XFocusinEvent data structure with NotifyPointer as the detail field. 


e When the focus moves from window A to PointerRoot (events sent to the window under 
the pointer) or the value of None (discards the event), and the pointer is in Window P, the 
X Server does the following: 


— If window P is an inferior of window A, the X Server generates a FocusOut event on 
each window from window P up to, but not including, window A that has the 
XFocusOutEvent data structure with NotifyPointer as the detail field. 


— A FocusOut event on window A that has the XFocusOutEvent data structure with 
NotifyNoniinear as the detail field. 


— If window A is not a root window, the X Server generates a FocusOut event on each 
window above window A up to, and including, its root window, that has the 
XFocusOutEvent data structure with NotifyNonlinearVirtual as the detail field. 


— A Focusin event on the root window of all screens that has the XFocusInEvent data 
structure with NotifyPointerRoot or NotifyDetailNone as the detail field. 


— If the new focus window is PointerRoot, the X Server generates a Focusin event on 
each window from the root window of window P down to, and including window P that 
has the XFocusinEvent data structure with NotifyPointerRoot as the detail field. 


e When the focus moves from PolnterRoot or the value of None to window A with the 
pointer in window P, the X Server generates: 


- Ifthe old focus in PointerRoot, the X Server generates a FocusOut event on each 
window from window P up to, and including the root window of window P that has the 
XFocusOutEvent data structure with NotifyPointer as the detail field. 


— A FocusOut event on all root windows that have the XFocusOutEvent data structure 
with NotifyPointerRoot or NotifyDetaliNone as the defail field. 


— If window A is not a root window, the X Server generates a Focusin event on each 
window from the root of window A down to, but not including, window A that has the 
XFocusinEvent data structure with NotifyNonlinearVirtual as the detail field. 


— A Focusin event on window A that has the XFocusinEvent data structure with 
NotifyNonlinear as the detail field. 


— lf window P is an inferior of window A, the X Server generates a Focusin event on 
each window below window A down to, and including, window P that has the 
XFocusinEvent data structure with NotifyPointer as the detail field. 


e When the focus moves from PointerRoot to the value of None, or vice versa, with the 
pointer in window P, the X Server generates: 


~ Ifthe old focus is PointerRoot, the X Server generates a FocusOut event on each 
window from window P up to, and including the root of window P that has the 
XFocusOutEvent data structure with NotifyPointer as the detail field 


~ Generates a FocusOut event on all root windows that have the XFocusOutEvent 
data structure with NotifyPointerRoot or NotifyDetallNone as the detail field. 


~ A Focusin event on all root windows that have the XFocusInEvent data structure with 
NotifyDetaiiNone or NotifyPointer as the detail field. 
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— If the new focus is PointerRoot, the X Server generates a Focusin event on each 
window from the root of window P down to, and including, window P that has the 
XFocusinEvent data structure with NotlfyPointer as the detail field. 


Using Enhanced X-Windows to Process Focus Events Generated by 
Grabs 
Focus events in which the keyboard grab activates are identified by XFocusinEvent or 
XFocusOutEvent data structures whose mode field is NotifyGrab. 


When a keyboard grab activates before generating an actual KeyPress event to the grab 
with window G (the grab_window) and to window F (the current focus window), the X Server 
generates Focusin and FocusOut events if the XFocusiInEvent and XFocusOutEvent 
data structures have NotifyGrab as the mode fields. These events are generated as if the 
focus had changed from window F to window G. 


Focus events in which the keyboard grab deactivates are identified by XFocusinEvent or 
XFocusOutEvent data structures whose mode field is NotifyUngrab. 


When a keyboard grab deactivates after generating an actual KeyRelease event that 
deactivates the grab with window G (the grab_window) and window F (the current focus 
window), the X Server generates Focusin and FocusOut events if XFocusinEvent and 
XFocusOutEvent data structures have NotifyUngrab as the mode fields. These events are 
generated as if the focus had changed from window G to window F. 


Using Enhanced X-Windows to Process Keymap State Notification 
Events 
The X Server reports KeymapNotify events to clients requesting information about changes 
in the keyboard state. To receive KeymapNotify events in a client application, pass a 
window ID and KeymapStateMask as the EventMask parameter to the XSelectinput 
subroutine. The X Server generates this event immediately after every EnterNotify and 
Focusin event. 


These event types use the XKeymapEvent data structure. 


Using Enhanced X-Windows to Process Expose Events 
The X protocol does not guarantee to preserve the contents of window regions when the 
windows are obscured or reconfigured. Some implementations can preserve the contents of 
windows, but many other implementations destroy the contents of windows when the 
windows are exposed. Client applications should be designed to restore the contents of an 
exposed window region. (An exposed window region describes a formerly obscured window 
whose region or piece of a region becomes visible.) the X Server sends exnosure events 
describing the window and the region of the window that has been exposed. Some client 
applications redraw the entire window, while other client applications redraw only the 
exposed region. 


The X Server reports Expose events to clients requesting information about when the 
contents of the window regions have been lost. The X Server generates Expose events 
when a window region becomes viewable. It reports Expose events contiguously when all 
the regions are exposed by some action, such as raising a window. The X Server cannot 
generate Expose events to InputOnly windows. 


To receive Expose events in a client application, pass a window ID and ExposureMask as 
the EventMask parameter to the XSelectinput subroutine. 


Use the XExposeEvent data structure with Expose events. 
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Using Enhanced X-Windows to Process GraphicsExpose and NoExpose 


Events 


The X Server reports GraphicsExpose events to clients requesting information when a 
destination region could not be computed during a graphics request. Clients initiate graphics 
request with the XCopyArea or XCopyPlane subroutines. 


The X Server generates a GraphicsExpose event whenever a destination region cannot be 
computed because of an obscured or out-of-bounds source region. The X Server reports 
contiguously all of the regions exposed by a graphics request (for example, copying an area 
of a drawable to a destination drawable). 


The X Server generates NoExpose events whenever a graphics request that might produce 
a GraphicsExpose event does not produce any graphics events. In other words, the client 
requests a GraphicsExpose event, but receives a NoExpose event instead. 


To receive GraphicsExpose or NoExpose events in a client application, set the 
graphics_exposures field of the XGCValues data structure to the value of True. The 
graphics_exposures field is set using the XCreateGC or XSetGraphicsExposures 
subroutines. 


Use the XGraphicsExposeEvent and the XNoExposeEvent data structures for these event 
types. 


Using Enhanced X-Windows to Process CirculateNotify Events 


The X Server reports CirculateNotify events to clients requesting information about when a 
window changes its position in the stack. The X Server generates this event type whenever 
a window is actually restacked as a result of a client application calling the 
XCirculateSubwindows, XCirculateSubwindowsUp, or XCirculateSubwindowsDown 
subroutines. 


To receive CirculateNotify events in a client application, set the event_mask field of the 
window to StructureNotifyMask or the event_mask field of the parent window to 
SubstructureNotifyMask. 


Use the XCirculateEvent data structure for this event type. 


Using Enhanced X-Windows to Process ConfigureNotify Events 


The X Server reports ConfigureNotify events to clients requesting information about actual 
changes to the state of a window, for example, size, position, border, and stacking order. It 
generates a ConfigureNotify event when a client application completes one of the following 
configure window subroutines: 


e XConfigureWindow which reconfigures window size, position, border, and stacking 
order. 


e XLowerWindow, XRalseWindow, or XRestackWindows which change the window 
position in the stacking order. 


e XMoveWindow which moves the window. 

e XResizeWindow which changes the window size. 

e XMoveResizeWindow which changes the size and location of the window. 

e XMapRalsed which changes the position of a mapped window in the stacking order. 
e XSetWindowBorderWidth which changes the border width of a window. 
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To receive a ConfigureNotify event, set the event_mask field of the window to 
StructureNotifyMask or the event_mask field of the parent window to 
SubstructureNotifyMask. 


Use the XConfigureEvent data structure for this event type. 


Using Enhanced X-Windows to Process CreateNotify Events 
The X Server reports CreateNotify events to clients requesting information about creation of 
windows. The X Server generates this event when a client application creates a window with 
the XCreateWindow or XCreateSimpleWindow subroutine. 


To receive CreateNotify events, set the event_mask field of the window to 
SubstructureNotifyMask. Creating any children then generates an event. 


Use the XCreateWindowEvent data structure for this event type. 


Using Enhanced X-Windows to Process DestroyNotify Events 
The X Server reports DestroyNotify events to clients requesting information about windows 
that are destroyed. It generates this event whenever a client application destroys a window 
with the XDestroyWindow or XDestroySubwindows subroutines. 


A DestroyNotify event is generated on all inferiors of a window before being generated on 
the window itself. The ordering among siblings and across subhierarchies is not constrained 
otherwise by the X protocol. 


To receive DestroyNotify events, set the event_mask field of the window to 
StructureNotifyMask or the event_mask field of the parent to SubstructureNotifyMask. 


Use the XDestroyWindowEvent data structure for this event type. 


Using Enhanced X-Windows to Process GravityNotify Events 
The X Server reports GravityNotify events to clients requesting information when a window 
is moved because of a change in the size of the parent window. The X Server generates this 
event when a client application moves a child window as a result of resizing its parent using 
the XConfigureWindow, XMoveResizeWindow, or XResizeWindow subroutine. 


To receive GravityNotify events, set the event_mask field of the window to 
StructureNotifyMask or the event_mask field of the parent to SubstructureNotifyMask. 


Use the XGravityEvent data structure for this event type. 


Using Enhanced X-Windows to Process MapNotify Events 
The X Server reports MapNotify events to clients requesting information about which 
windows are mapped. It generates this event type whenever a client application changes the 
state of a window from unmapped to mapped with the XMapWindow, XMapRaised, or 
XMapSubwindows subroutines. 


To receive MapNotify events, set the event_mask field of the window to 
StructureNotifyMask or the event_mask field of the parent to SubstructureNotifyMask. 


Use the XMapEvent data structure for this event type. 
Using Enhanced X-Windows to Process MappingNotify Events 
The X Server reports MappingNotify events to all clients. There is no mechanism to cancel 


generation of this event. The X Server generates this event whenever a olen calls one of 
the following subroutines: 
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XSetModifierMapping Specifies the keycodes to be used as modifiers. 
XChangeKeyboardMapping Changes the keyboard mapping. 
XSetPointerMapping Sets the pointer mapping. 

Use the XMappingEvent data structure for this event. 


Using Enhanced X-Windows to Process ReparentNotify Events 
The X Server reports ReparentNotify events to clients requesting information about 
changing the parent of a window. It generates this event when a client application calls the 
XReparentWindow subroutine and the window is actually reparented. 


To receive ReparentNotify events, set the event_mask field of the window to 
StructureNotifyMask or the event_mask field of either the old or the new parent to 
SubstructureNotifyMask, in which case reparenting any child generates an event. 


Use the XReparentEvent data structure for this event type. 


Using Enhanced X-Windows to Process UnmapNotify Events 
The X Server reports UnmapNotify events to clients requesting information about which 
windows are unmapped. The X Server generates this event whenever a client application 
changes the window state from mapped to unmapped with the XUnmapWindow or 
XUnmapSubwindows subroutine. 


To receive UnmapNotify events, set the event_mask field of the window to 
StructureNotifyMask or the event_mask field of the parent to Substructure NOtty Mes: in 
which case unmapping the child generates the event. 


Use the XUnmapEvent data structure for this event type. 


Using Enhanced X-Windows to Process VisibilityNotify Events 
The X Server reports VisibilityNotify events to clients requesting any change in the visibility 
of the specified window. (A region of a window is visible if it can actually be seen on the 
screen.) The X Server generates this event whenever the visibility of the window changes 
state. However, VisibilityNotify events are not generated for InputOnly windows or 
subwindows. 


All VisibilityNotify events caused by a hierarchy change are generated after any hierarchy 
event (UnmapNotify, MapNotify, ConfigureNotify, GravityNotify, CirculateNotify) 
caused by that change. Any VisibilityNotify event on a window is generated before any 
Expose events on that window, but it is not required that all VisibilityNotify events on all 
windows are generated before all Expose events on all windows. The ordering of 
VisibilityNotify events with respect to FocusOut, EnterNotify, and LeaveNotify events is 
not constrained by the X protocol. 


The X Server ignores all the subwindows in determining the visibility state of a specified 
window and processes VisibilityNotify events according to the following: 


e When the window changes state from partially obscured, fully obscured, or not viewable 
to viewable and completely unobscured, the X Server generates the event with 
VisibilityUnobscured as the state field of the XVisibilityEvent structure. 


e When the window changes state from viewable and completely unobscured or not 
viewable to viewable and partially obscured, the X Server generates the event with 
VisibilityPartiallyObscured as the state field of the XVisibilityEvent structure. 


e When the window changes state from viewable and completely unobscured, viewable and 
partially obscured, or not viewable to viewable and fully obscured, the X Server generates 
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the event with VisibilityFullyObscured as the state field of the 
XVisibilityEvent structure. 


To receive VisibilityNotify events, set the event_mask field of the window to 
VisibilityChangeMask. 


Use the XVisibilityEvent data structure for this event type. 


Using Enhanced X-Windows to Process CirculateRequest Events 
The X Server reports CirculateRequest events to clients requesting information about when 
another client initiates a window request on a specified window. The X Server generates this 
event type when a client initiates a circulate window request on a window and a subwindow 
needs to be restacked. The client initiates a circulate window request with the 
XCirculateSubwindows, XCirculateSubwindowsUp, or 
XCirculateSubwindowsDown subroutines. 


To receive a CirculateRequest event, set the event_mask field of the window to 
SubstructureRedirectMask. Then, in the future, a circulate window request for the 
specified window will not be executed and the position of the window in the stack is not 
changed. Instead, the client will receive a CirculateRequest event. 


Use the XCirculateRequestEvent data structure for this event type. 


Using Enhanced X-Windows to Process ConfigureRequest Events 
The X Server reports ConfigureRequest events to clients requesting information about 
when another client initiates a configure request on any child of a specified window. The 
configure window request attempts to reconfigure the window size, position, border, or 
stacking order. The X Server generates this event whenever a different client initiates a 
configure window request on a window by using the XConfigureWindow, XLowerWindow, 
XRaiseWindow, XMapRaised, XMoveResizeWindow, XMoveWindow, XResizeWindow, 
XRestackWindows, or XSetWindowBorderWidth subroutines. 


To receive ConfigureRequest events, set the event_mask field of the window to 
SubstructureRedirectMask. 


Use the XConfigureRequestEvent data structure for this event type. 


Using Enhanced X-Windows to Process MapRequest Events 
The X Server reports MapRequest events to clients wanting information about a request by 
another client to map windows. (A window is considered mapped when a map window 
request completes.) The X Server generates this event whenever a different client initiates a 
map window request on an unmapped window whose override_redirect field is the value of 
False. Clients can initiate map window requests using the XMapWindow, XMapRaised, or 
XMapSubwindows subroutines. 


To receive MapRequest events, set the SubstructureRedirectMask bit in the event_mask 
field of the window. This means that another client's attempts to map a child window by 
calling one of the map window request subroutines is intercepted, and you are sent a 
MapRequest event instead. Thus, this event gives your window manager client the ability to 
control the placement of subwindows. 


Use the XMapRequestEvent data structure for this event type. 


Using Enhanced X-Windows to Process ResizeRequest Events 
The X Server reports ResizeRequest events to clients requesting information when another 
client attempts to change the size of a window. A client can attempt to change the size of a 
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window by calling the XConfigureWindow, XResizeWindow, or XMoveResizeWindow 
subroutines. 


To receive ResizeRequest events, set the ResizeRedirect bit in the event_mask field of the 
window. Any attempts by other clients to resize the window are then redirected. 


Use the XResizeRequestEvent data structure for this event type. 


Using Enhanced X-Windows to Process Colormap State Notification 
Events 
The X Server reports ColormapNotify events to clients requesting information about when 
the colormap changes and when a colormap is installed or uninstalled. The X server 
generates this event type whenever a client application: 


e Changes the colormap field of the XSetWindowAttributes structure using the 
XChangeWindowAtiributes, XFreeColormap, or XSetWindowColormap subroutines. 


e Installs or uninstalls the colormap using the X!InstallColormap or XUninstaliColormap 
subroutines. 


To receive ColormapNotify events, set the ColormapChangeMask bit in the event_mask 
field of the window. 


Use the XColormapEvenit data structure for this event type. 


Using Enhanced X-Windows to Process ClientMessage Events 
The X Server generates ClientMessage events when a client calls the XSendEvent 
subroutine. The XSendEvent subroutine identifies the destination window, determines which 
clients should receive the specified events, and ignores any active grabs. 


Use the XClientMessageEvent data structure for this event type. 


Using Enhanced X-Windows to Process PropertyNotify Events 
The X Server reports PropertyNotify events to clients requesting information about property 
changes for a specified window. The X Server generates this event when a client application 
calls the XChangeProperty, XDeleteProperty, XRotateWindowProperties, or 
XGetWIndowProperty subroutines. 


To receive PropertyNotify events, set the PropertyChangeMask bit in the event_mask 
field of the window. 


Use the XPropertyEvent data structure for this event type. 


Using Enhanced X-Windows to Process SelectionClear Events 
The X Server reports SelectionClear events to the current owner of a selection. This event 
is generated on the window losing ownership of the selection to a new owner. The X Server 
generates this event whenever a client calls the XSetSelectionOwner subroutine. 


Use the XSelectionClearEvent data structure for this event type. 
Using Enhanced X-Windows to Process SelectionRequest Events 
The X Server reports SelectionRequest events to the owner of a selection when a client 


requests a selection conversion using the XConvertSelection subroutine and the specified 
selection is owned by a window. 


The client that owns the selection should do the following: 


e Convert the selection based on the atom contained in the target field. 
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e Store the result as the property specified on the requestor window and send a 
SelectionNotify event to creator of the requestor window, if a value was specified in the 
Property field. 


e Choose a property name on the requestor window and send a SelectionNotify event 
giving the actual name, if the property field is the value of None. 


e Send a SelectionNotify event with the property field set to the value of None, if the 
selection cannot be converted as requested. 


Use the XSelectionRequestEvent data structure for this event type. 


Using Enhanced X-Windows to Process SelectionNotify Events 
The X Server generates SelectionNotify events in response to an XConvertSelection 
request when there is no owner for the selection. If the selection has an owner, the 
SelectionNotify event should be generated by the owner using the XSendEvent 
subroutine. 


If the selection has been converted and stored as a property or a selection conversion could 
not be performed, the SelectionNotify event should be sent to the requestor window. 


If the value of None is specified in the property field of the ConverSelection protocol 
request, the selection owner should choose a property name, store the result as that 
property on the requestor window, and then send a SelectionNotify event giving that actual 
property name. 


Use the XSelectionEvent data structure for this event type. 


Using Enhanced X-Windows to Select Events | 
There are two ways to select the events reported to your client application. One way is to set 
the event_mask field of the XSetWindowaAttributes data structure when you use the 
XCreateWindow and XChangeWindowaAttributes subroutine. The second way is to use 
the XSelectinput subroutine. 


Events are reported relative to a window. If a window requests an event, it usually 
propagates to the closest ancestor that does not request an event unless the 
do_not_propagate mask prohibits propagation. 


Setting the event_mask field of a window overrides any previous call to the same window 
from the same client, but not from other clients. Multiple clients can select for the same 
events on the same window with the following restrictions: 


e Multiple clients can select events on the same window because the event masks are 
disjointed. After ine X Server generates an eveni, it reporis the event to aii interested 
Clients. 


e Only one client at a time can select the CirculateRequest, ConfigureRequest, or 
MapRequest events, which are associated with the SubstructureRedirectMask event 
mask. 


e Only one client at a time can select a ResizeRequest event, which is associated with the 
ResizeRedirectMask event mask. 


e Only one client at a time can select a ButtonPress event, which is associated with the 
ButtonPressMask event mask. 


The server reports the event to all interested clients. 
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Using Enhanced X-Windows to Handle the Output Buffer and the Event 

Queue 
Under some circumstances, event subroutines flush the output buffer. The output buffer is an 
area used by the Xlib library to store requests. Some event subroutines flush the output 
buffer if the subroutine would block or not return an event. All requests residing in the output 
buffer that have not yet been sent are transmitted to the X Server. Conversely, these 
subroutines differ in the additional tasks they might perform. For example, the XSync 
subroutine not only flushes the output buffer, but it can also discard all events in the event 
queue. 


Using Enhanced X-Windows to Select Events Using a Predicate 
Procedure 
The XifEvent, XChecklfEvent, and XPeekifEvent subroutines require a predicate 
procedure that determines if the event matches the event specified in the corresponding 
subroutine. The predicate procedure must decide only if the event is useful and must not call 
the Xlib library subroutines. This predicate procedure is called from within the event routine, 
which must lock so that the event queue is consistent in a multi-threaded environment. 


The predicate procedure for these subroutines is defined as: 


Bool (*predicate)(DisplayPtr, Event, Arguments); 
Display *DisplayPrtr, 

XEvent * Event; 

char “Arguments; 


displayptr Specifies the connection to the X Server. 
event Specifies a pointer to the XEvent structure. 


arguments Specifies the arguments passed in from the XifEvent, XCheckifEvent, or 
XPeeklfEvent subroutines. 


The predicate procedure is called once for each event in the queue until it finds a match 
between the event in the queue and the event specified by the corresponding subroutine. 
This procedure returns the value of True if it finds a match. It returns the value of False if it 
does not find a match. 


Using the Enhanced X-Windows Default Error Handler 
Two default error handlers reside in the library. One is used for typically fatal conditions (for 
example, the connection to the display fails due to a system crash), while the other is used 
for error events from the X Server. These error handlers can be changed to user-supplied 
routines as often as necessary. To reinvoke either error handler, pass the value of NULL 
pointer. The default is to print an explanatory message and exit. 


Use the XErrorEvent data structure for this event type. 


Related Information 
The XAnyEvent data structure, XButtonPressedEvent data structure, 
XButtonReleasedEvent data structure, XCirculateEvent data structure, 
XCirculateRequestEvent data structure, XClientMessageEvent data structure, 
XColormapEvent data structure, XConfigureEvent data structure, 
XConfigureRequestEvent data structure, XCreateWindowEvent data structure, 
XCrossingEvent data structure XDestroyWindowEvent data structure, 
XEnterWindowEvent data structure, XErrorEvent data structure, XEvent data structure, 
XExposeEvent data structure, XFocusChangeEvent data structure,, XFocusiInEvent data 
structure, XFocusOutEvent data structure, XGCValues data structure 
XGraphicsExposeEvent data structure, XGravityEvent data structure, 
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XKeyPointerMovedEvent data structure, XKeyPressedEvent data structure, 
XKeyReleasedEvent data structure, XKeymapEvent data structure, XLeaveWindowEvent 
data structure, XMapEvent data structure, XMappingEvent data structure, 
XMapRequestEvent data structure, XNoExposeEvent data structure, XPropertyEvent 
data structure, XReparentEvent data structure, XResizeRequestEvent data structure, 
XSelectionClearEvent data structure, XSelectionEvent data structure, 
XSelectionRequestEvent data structure, XUnmapEvent data structure, XVisibilityEvent 
data structure. 


The ButtonPress event, ButtonRelease event, CirculateNotify event, CirculateRequest 
event, ClientMessage event, ColormapNotify event, ConfigureNotify event, 
ConfigureRequest event, CreateNotify event, DestroyNotify event, EnterNotify event, 
Expose event, Focusin event, FocusOut event, GraphicsExposure event, GravityNotify 
event, KeyPress event, KeyRelease event, KeymapNotify event, LeaveNotify event, 
MapNotify event, MapRequest event, MappingNotify event, MotionNotify event, 
NoExposure event, PropertyNotify event, ReparentNotify event, ResizeRequest event, 
SelectionClear event, SelectionNotify event, SelectionRequest event, UnmapNotify 
event, VisibilityNotify event. 


The <X11/X.h> header file, <X11/Xlib.h> header file, <X11/Xproto.h> header file. 


The IsCursorKey macro, IsFunctionKey macro, IsKeypadKey macro, 
IsMiscFunctionKey macro, IsModifierKey macro, IsPFKey macro. 


The XChangeActivePointerGrab subroutine, XChangeGC subroutine, 
XChangeKeyboardMapping subroutine, XChangeProperty subroutine, 
XChangeWindowéAttributes subroutine, XChecklfEvent subroutine, XCheckMaskEvent 
subroutine, XCheckTypedEvent subroutine, XCheckTypedWindowEvent subroutine, 
XCheckWindowEvent subroutine, XCirculateSubwindows subroutine, 
XCirculateSubwindowsDown subroutine, XCirculateSubwindowsUp subroutine, 
XConfigureWindow subroutine, XConvertSelection subroutine, XCopyArea subroutine, 
XCopyPlane subroutine, XCreateGC subroutine, XCreateSimpleWindow subroutine, 
XCreateWindow subroutine, XDeleteProperty subroutine, XDestroySubwindows 
subroutine, XDestroyWindow subroutine, XDisplayName subroutine, XEventsQueued 
subroutine, XFlush subroutine, XFreeColormap subroutine, XGetErrorDatabaseText 
subroutine, XGetErrorText subroutine, XGetInputFocus subroutine, 
XGetWindowProperty subroutine, XGrabButton subroutine, XGrabKeyboard subroutine, 
XGrabPointer subroutine, XlfEvent subroutine, XInstallColormap subroutine, 
XKeycodeToKeysym subroutine, XKeysymToKeycode subroutine, XKeysymToString 
subroutine, XLookupKeysym subroutine, XLookupString subroutine, XLowerWindow 
subroutine, XMapRaised subroutine, XMapSubwindows subroutine. XMapnWindow 
subroutine, XMaskEvent subroutine, XMoveResizeWindow subroutine, XMoveWindow 
subroutine, XNextEvent subroutine, XPeekEvent subroutine, XPeeklfEvent subroutine, 
XPending subroutine, XPutBackEvent subroutine, XRaiseWindow subroutine, 
XRebindKeysym subroutine, XRefreshKeyboardMapping subroutine, XReparentWindow 
subroutine, XResizeWindow subroutine, XRestackWindows subroutine, 
XRotateWindowProperties subroutine, XSelectInput subroutine, XSendEvent subroutine, 
XSetErrorHandler subroutine, XSetGraphicsExposures subroutine, XSetinputFocus 
subroutine, XSetiOErrorHandler subroutine, XSetModifierMapping subroutine, 
XSetPointerMapping subroutine, XSetSelectionOwner subroutine, 
XSetWindowdAttributes data structure, XSetWindowBorderWidth subroutine, 
XSetWindowColormap subroutine, XStringToKeysym subroutine, XSyne subroutine, 
XWindowEvent subroutine, XUngrabKeyboard subroutine, XUngrabPointer subroutine, 
XUninstallColormap subroutine, XUnmapSubwindows subroutine, XUnmapWindow 
subroutine, XWarpPointer subroutine. 
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Enhanced X-Windows Graphics Resource Subroutines 
Overview 


Enhanced X-Windows graphics resource subroutines allow you to manipulate colormaps, 
pixmaps, graphics context (GC) state and use GC convenience routines. 


A number of resources are used when performing graphics operations in Enhanced 
X-Windows. Most attributes of graphics operations (for example, foreground color, 
background color, line style, and other graphics) are stored in resources called graphics 
contexts (GC). Most graphics operations take a graphics context (GC) as an argument. 
While sharing GCs between applications is possible, it is not encouraged. Applications 
should use their own GCs when performing operations. 


Windows have a colormap associated with them that provides a level of indirection between 
pixel values and color displayed on the screen. Many hardware displays have a single 
colormap; therefore, the primitives are written to share colormap entries between 
applications. Because colormaps are associated with windows, Enhanced X-Windows 
supports displays with multiple colormaps and different types of colormaps. If there are not 
enough colormap resources in the display, some windows may not be displayed in their true 
colors. A window manager can set the displayed windows in their true colors if more than 
one colormap is required for the color resources the applications are using. 


Off-screen memory or pixmaps are often used to define frequently-used images for later use 
in graphics operations. Pixmaps are also used to define tiles or patterns for window 
backgrounds, borders, or cursors. (A single-bit plane pixmap is sometimes referred to as a 
bitmap). There may not be an unlimited amount of off-screen memory; therefore, it should be 
regarded as a precious resource. 


Graphics operations can be performed to windows or pixmaps, which are also called 
drawables. Each drawable exists on a single screen or root window. The drawable can be 
used only on that root window. GCs can be used with drawables of matching root windows 
and depths. 


Creating Enhanced X-Windows Colormaps 
The Xlib library provides subroutines to create, allocate, free, set and manipulate colormaps. 
The introduction of color changes the view a programmer should take when dealing with a 
bitmap display. For example, when printing text, you write in a color or pixel value rather 
than by setting or clearing bits. Hardware imposes limits (number of significant bits, for 
example). Typically, you allocate particular pixel values or sets of values. If read-only, the 
pixel values can be shared among multiple applications. If read/write, the pixel values are 
exclusively owned by the program, and the color cell associated with the pixel value can be 
changed at will. 


Each pixel on a monochrome (black and white) display has one bit of information associated 
with it; the bit is either zero (0) or one (1). 


Color displays, however, need multiple bits per pixel to properly regulate the red, green, and 
blue color guns that provide the full range of visible colors available to the particular display. 
For example, assume a display has 4 bits per pixel, numbered 0, 1, 2, and 3. The display is 
said to be 4 planes deep. One plane contains all the bit Os, the second contains the bit 1s, 
the third contains the bit 2s, and the fourth contains the bit 3s. 


Some subroutines manipulate the representation of color on the screen. For each possible 
value a pixel can take on a display, a color cell is defined in the colormap. For example, if a 
display is 4 bits deep, pixel values 0 through 15 are defined. A colormap is a collection of the 
color cells. A color cell consists of a triple of red, green, and blue. As each pixel is read out 
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of display memory, its value is taken and looked up in the colormap. The values of the cell 
determine what color is displayed on the screen. On a multiplane display with a black and 
white monitor (grayscale, but not color), these values may be combined to determine the 
brightness on the screen. 


One or more colormaps may reside at one time on certain hardware. The XInstallColormap 
subroutine installs a colormap; while the DefaultColormap macro returns the default 
colormap. The DefaultVisual macro returns the default visual type for the specified screen. 
Colormaps are local to a particular screen. Possible visual types are represented by 
StaticGray, GrayScale, StaticColor, PseudoColor, TrueColor, or DirectColor. 


Allocating Enhanced X-Windows Colormaps 
The Xlib library provides subroutines to allocate or deallocate pixel values for colors that you 
need to display. There are two ways of allocating color cells: explicitly as read only entries 
by pixel value or as read/write entries, where you can allocate a number of color cells and 
planes simultaneously. The read or write cells allocated are not defined colors until the 
colors are set with the XStoreColor or the XStoreColors subroutine. 


Screens always have a default colormap. Programs typically allocate cells out of a common 
colormap. Writing applications that monopolize color resources is discouraged. On a screen 
that cannot load the colormap or cannot have a fully independent colormap, only certain 
kinds of allocations work. 


To determine the color names, the X Server uses a color database. On an AlX-based 
system, this database is /usr/lpp/X11/rgb/rgb. A printable copy of this database is stored in 
/usr/lpp/X11/rgb/rgb.txt. 


The name and contents of this file are operating-system specific and possibly screen 
specific. Although you can change the values in a read/write color cell that is allocated by 
another application, this is not encouraged. 


Manipulating Enhanced X-Windows Standard Colormaps 
Applications with color palettes, smooth-shaded drawings, or digitized images demand large 
numbers of colors. In addition, these applications often require an efficient mapping from 
color triples to pixel values that display the appropriate colors. 


As an example, consider a 3D display program designed to draw a smoothly shaded sphere. 
At each pixel in the image of the sphere, the program computes the intensity and color of 
light reflected back to the viewer. The result of each computation is a triple of red, green, and 
blue co-efficients in the range 0.0 to 1.0. To draw the sphere, the program needs a colormap 
that provides a large range of uniformly distributed colors. The colormap should be arranged 
so that the nrogram can convert its RGB triples into pixel values very quickiy because 
drawing the entire sphere requires many such conversions. 


On many current workstations the display is limited to 256 or fewer colors. Applications must 
allocate colors carefully, not only to make sure they cover the entire range needed, but also 
to make use of as many of the available colors as possible. On a typical X Server display, 
many applications are active at once. Most workstations have only one hardware lookup 
table for colors; therefore, only one application colormap can be installed at a given time. 
The application using the installed colormap is displayed correctly while the other 
applications are displayed with false colors. 


As another example, consider users who run an image processing program to display 
earth-resources data. The image processing program needs a colormap set up with 8 reds, 
8 greens, and 4 blues which is a total of 256 colors. Because some colors are already in use 
in the default colormap, the image processing program allocates and installs a new 
colormap. 
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The users decide to alter some of the colors in the image. They invoke a color palette 
program to mix and choose colors. The color palette program also needs a colormap with 8 
reds, 8 greens, and 4 blues; therefore, just as the image-processing program, the color 
palette program must allocate and install a new colormap. 


Because only one colormap can be installed at a time, the color palette can be displayed 
incorrectly when the image-processing program is active. Conversely, when the palette 
program is active, the image can be displayed incorrectly. Users can never match or 
compare colors in the palette and image. Contention for colormap resources can be reduced 
if applications with similar color needs share colormaps. 


As another example, the image processing program and the color palette program share the 
same colormap if there exists a convention that describes how the colormap is set up. 
Whenever either program is active, both are displayed correctly. 


The standard colormap properties define a set of commonly used colormaps. Applications 
that share these colormaps and conventions display true colors more often and pionce a 
better interface to the users. 


Using Enhanced X-Windows Standard Colormaps 
Standard colormaps allow applications to share commonly used color resources. This 
feature allows many applications to be displayed in true colors simultaneously, even when 
each application needs an entirely filled colormap. 


Several standard colormaps are described. Usually, these colormaps are created by a 
window manager. Applications should use the standard colormaps if they already exist. If the 
standard colormaps do not exist, applications should create new standard colormaps. 


Using Enhanced X-Windows Standard Colormap Properties and Atoms 
Several standard colormaps are available. Each standard colormap is defined by a property, 
and each property is identified by an atom. The following is a list of atom names and the 
colormap associated with each one. 


e The RGB_DEFAULT_MAP atom names a property with the value of 
XStandardColormap. The property defines an RGB subset of the system default 
colormap. Some applications need only a few RGB colors and may be able to allocate 
these colors from the system default colormap. By using the system default colormap, you 
ensure that there are fewer active colormaps in the system. This, in turn, ensures that 
your application is more likely to be displayed with the correct colors at all times. 


A typical allocation for the RGB_DEFAULT_MAP on 8-plane displays is 6 reds, 6 greens, 
and 6 blues. This allocation gives 216 uniformly distributed colors (6 intensities of 36 
different hues) and still leaves 40 elements of a 256-element colormap available for 
special-purpose colors for text, borders and other fields. 


e The RGB_BEST_MAP atom names a property with the value of XStandardColormap. 
The property defines the best RGB colormap available on the display. 


Many image processing and 3D applications need to use all available colormap cells and 
distribute as many perceptually distinct colors as possible over those colormap cells. This 
implies that more green values may be available than red values, as well as more green 
values or red values than blue values. 


On an 8-plane pseudocolor display, RGB_BEST_MAP is a 3/3/2 allocation. Ona 
24-plane direct color display, RGB_BEST_MAP is an 8/8/8 allocation. On other 
displays, RGB_BEST_MAP allocation is set by the user or the owner of the display. 


e The RGB_RED_MAP atom names a property with the value of XStandardColormaps. 
This property defines an all-red colormap, which is used to make color-separated images. 
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e The RGB_GREEN_MAP atom names a property with the value of 
XStandardColormaps. This property defines an all-green colormap, which is used to 
make color-separated images 


e The RGB_BLUE_MAP atom names a property with the value of XStandardColormaps. 
This property defines an all-blue colormap, which is used to make color-separated 
images. 


For example, a user might generate a full-color image on an 8-plane display both by 
rendering an image three times (once with high color resolution in red, once with high 
color resolution in green, and once with high color resolution in blue) and by 
multiple-exposing a single frame in a camera. 


e The RGB_GRAY_MAP atom names a property with the value of XStandardColormap. 
This property describes the best gray-scale colormap available on the display. 


Determining Enhanced X-Windows Resident Colormaps 
Window manager applications usually install and uninstall colormaps. Thus, these tasks 
should not be performed by normal client applications. 


The X Server maintains a subset of the installed colormaps in an ordered list called the 
required list. The length of the required list is the minimum number of installed colormaps 
specified for the screen when the connection is opened to the server. Initially, only the 
default colormap for a screen is installed, but it is not in the required list. The X Server 
maintains the required list as follows: 


e If acolormap resource ID is passed to the ColorMap argument, the XInstaliColormap 
subroutine adds the colormap to the top of the list. If necessary, it ttuncates a colormap at 
the bottom of the list so that the maximum length of the list is not exceeded. 


e If acolormap resource ID is passed to the ColorMap argument and this colormap is in the . 
required list, the XUninstallColormap subroutine removes the colormap from the 
required list. 


A colormap is not implicitly added to the required list when it is installed by the server. Nor is 
a colormap in the required list implicitly uninstalled by the server. 


Reading Enhanced X-Windows Entries in a Colormap 
The XQueryColor and XQueryColors subroutines return the red, green, and blue color 
values stored in the specified colormap for the pixel value passed in the pixel field of the 
XColor data structures. The values returned for an unallocated entry are undefined. These 
subroutines also set the flags field in the XColor data structure to all three colors. 


Creating and Freeing Enhanced X-Windows Pixmaps 
A pixmap is a rectangle of pixels that has the width and the height in pixels. A pixmap is as 
deep as the pixel has bits. Pixmaps are used only on the screen on which they are created. 
Pixmaps can be represented in storage in either XYformat or Zformat. 


In XYformat, each plane in the pixmap is represented as a bitmap; the bitmaps appear in 
storage from most significant to least significant in sequence. 


In Zformat, the pixels are stored row by row, top to bottom, left to right within the row. 


The Xlib library provides subroutines to create or free a pixmap. Pixmaps can be used for 
operations such as defining cursors as tiling patterns or as the source for certain raster 
operations. Most graphic requests can operate on a window or a pixmap. Some programs 
may want to manipulate pixels that are displayed on the screen later. Some subroutines 
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move pixels from the program to the window system or from the window system to the 
program. 


Defining Enhanced X-Windows Bitmaps 
A bitmap is a rectangle of bits that has a width in pixels and a height in pixels. A bitmap is a 
pixmap of depth one. At depth one, Z format and XYformat are identical and are not 
specified in a bitmap. 


Manipulating Enhanced X-Windows Graphics Context or State 
Most components of graphics operations are stored in graphics contexts (GCs). These 
components include line width, line style, plane mask, foreground, background, tile, stipple, 
clipping region, end style, join style, and others. Graphics operations (for example, drawing 
lines) use these values to determine the actual drawing operation. Extensions to Enhanced 
X-Windows may add more components to GCs. The Xlib library provides calls for changing 
the state of GCs. 


The Xlib library implements a write-back cache for all elements of a GC that are not 
resource IDs to allow it to implement the transparent coalescing changes to GCs. GCs are 
neither expected nor encouraged to be shared between client applications; therefore, this 
write-back caching should not present problems. Applications cannot share GCs without 
external synchronization; therefore, sharing GCs between applications is not encouraged. 


The specified fields of the new graphics context in ValuemaskCreate are set to the values 
passed in the values parameter. The other fields default to the following values: 
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The function field of the GC is used when a section of the destination screen is updated with 
source bits from somewhere else. The function field defines how the new destination bits are 
to be computed from the source bits and the old destination bits. 


The GXcopy value is typically the most useful function because it works on a color display, 
but special applications can use other functions, particularly with certain planes of a color 
display. The functions, which are defined in <X11/X.h>, are: 
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source OR (NOT destination) 
GXorlnverted 


(NOT source) OR destination 
(NOT source) OR (NOT destination) 


Note: Using display functions other than GXcopy, such as GXxor and GXinvert, on a color 
display can result in undefined pixel values. 









For example, if an X Server on a four-plane display performs the GXinvert on pixel value 3, 
ine resuit is pixel value 12. The color currently associated with pixel value 12 is displayed, 
whether or not it is a defined value. 


Many graphics operations depend on either pixel values or planes in a GC. The plane_mask 
field specifies which planes of the display are to be modified (one bit per plane). A 
monochrome display has only one plane and this plane is the least-significant bit of the 
word. As planes are added to the display hardware, they occupy more significant bits in the 
plane mask. 


In graphics operations, given a source and destination pixel, the result is computed bitwise 
on corresponding bits of the pixels. That is, a Boolean operation is performed in each bit 
plane. The plane_mask field restricts the operation to a subset of planes. The AllPlanes 
macro can be used to refer to all planes of a display simultaneously. The result is computed 
by the following: 


((src FUNC dst) AND plane-mask) OR (dst AND (NOT plane-mask) ) 
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Most operations use a GC. The contents of the GC are private to the Xlib library. Several 
procedures take structures from the XGCValues data structure. 


Related Information 
The XColor data structure, XGCValues data structure. 


The XAllocColor subroutine, XAllocColorCells subroutine, XAllocColorPlanes 
subroutine, XAllocNamedColor subroutine, XCopyColormapAndFree subroutine, 
XCreateColormap subroutine, XCreateGC subroutine XCreatePixmap subroutine, 
XFreeColormap subroutine, XFreeColors subroutine, XFreePixmap subroutine, 
XGetStandardColormap subroutine, XInstallColormap subroutine, 
XListinstalledColormaps subroutine, XLookupColor subroutine, XQueryColor 
subroutine, XQueryColors subroutine, XSetStandardColormap subroutine, 
XSetWindowColormap subroutine, XStoreColor subroutine, XStoreColors subroutine, 
XStoreNamedColor subroutine, XUninstallColormap subroutine 


Enhanced X-Windows Graphics Subroutines Overview 
The Xlib library graphics subroutines allow you to perform the following tasks: 
e Clear and copy areas 
e Draw points, lines, rectangles, and arcs 
e Fill areas 
e Manipulate fonts 
e Draw text characters 
e Transfer images between clients and server 


e Manipulate cursors. 


Using Enhanced X-Windows to Clear Areas 
Some Xlib library subroutines allow you to clear an area or an entire window. The 
XClearArea subroutine clears a specified rectangular area in a window, while the 
XClearWindow subroutine clears the entire window. 


Pixmaps do not have defined backgrounds; therefore, pixmaps cannot be filled by the 
XClearArea or XClearWindow subroutines. Instead, use the XFillRectangle subroutine, 
which sets the pixmap to a known value. 


Using Enhanced X-Windows to Copy Areas 
The XLib library provides subroutines that you can use to copy an area or a bit plane. When 
using the XCopyArea subroutine to copy a specified area, the source drawable and the 
destination drawable must have the same root window and the same depth. When using the 
XCopyPlane subroutine to copy a single bit-plane to a drawable with depth >1, the bit plane 
is color-expanded to the depth of the drawable. In the source drawable, the one (1) bits 
cause the corresponding pixel in the destination drawable to be set to the foreground 
specified in the graphics context to alu the function and the planemask. In the same 
instance, the zero (0) bits in the source drawable cause the corresponding destination pixels 
to be set to the background color. 
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Using Enhanced X-Windows to Draw Points, Lines, Rectangles, and 
Arcs | . 
The Xlib library subroutines allow you to draw a single point or multiple points, a single line 
or multiple lines, a single rectangle or multiple rectangles, and a single arc or multiple arcs. 


If the same drawable and GC is used for each call, the Xlib library batches back-to-back 
Calls to the XDrawPoint, XDrawLine, XDrawRectangle, XFillArc, and XFillRectangle 
subroutines. 


Using Enhanced X-Windows to Draw Single and Multiple Points 
To draw single points, use the XDrawPoint subroutine. This subroutine uses the foreground 
pixel and function components of the GC to draw a single point into a drawable. This 
subroutine is not affected by the tile or stipple in the GC. 


To draw multiple points, use the XDrawPoints subroutine. With this subroutine, specify an 
array of XPoint data structures. The XDrawPoints subroutine uses the foreground pixel and 
function components of the GC to draw multiple points into a drawable. This subroutine is 
not affected by the tile or stipple in the GC. 


Using Enhanced X-Windows to Draw Single and Multiple Arcs 
To draw single and multiple arcs, use the XDrawAre subroutine and the XDrawArcs 
subroutine. The XDrawArc subroutine draws a single circular or elliptical arc, while the 
XDrawArcs subroutine draws multiple circular or elliptical arcs. Each arc drawn is specified 
by a rectangle and two angles. The center of the circle or ellipse is the center of the 
rectangle, and the major and minor axes are specified by the width and height. Positive 
angles indicate counterclockwise motion, while negative angles indicate clockwise motion. If 
the magnitude of angle2 is greater than 360 degrees, the XDrawArc or XDrawArcs 
subroutine truncates it to 360 degrees. 


The x and y coordinates of the rectangle are relative to the origin of the drawable. For an arc 
specified as [x,y,w,h,anglel,anglez2 }, the origin of the major and minor axes is at 
[x+(width/2),y+(height/2) }. 


The infinitely thin path describing the entire circle or ellipse intersects the horizontal axis at 
[x,y+(height/2) ] and [x+width,y+(height/2) ] and the vertical axis at 
[x+(width/2),y] and [x+(width/2),y+height]. These coordinates can be 
fractional. The paths should be defined by the ideal mathematical path. 


For a wide line with line-width lwidth, the bounding outlines for filling are given by the 
infinitely thin paths describing the arcs: 


[xt+dx/2, vtdy/2, width-dx, height-dy, angiei, angie2] 


and 
[x-lwidth/2, y-lwidth/2, widtht+lwidth, height+lwidth, anglel, 
angle2] 
where 


dx=min(lwidth,width) 
dy=min(lwidth,height) 


The cap-style and join-style are applied the same as for a line corresponding to the tangent 
of the circle or ellipse at the endpoint. 


For an arc specified as [x, y, width, height,anglel,angle2], the angles must be 
specified in the effectively skewed coordinate system of the ellipse; for a circle, the angles 
and coordinate systems are identical. The relationship between these angles and angles 
expressed in the normal coordinate system of the screen (as measured with a protractor) is 
as follows: 


skewed-angle = atan(tan(normal-angle) * width/height) + adjust 
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The skewed-angle and normal-angle are expressed in radians (rather than in degrees scaled 
by 64) in the range [0,2*Pl), and where atan returns a value in the range [-P1/2,PI/2], and 
where adjust is: 


0 for normal-angle in the range [0,PI/2] 
PI for normal-angle in the range [PI/2,(3*PI)/2) 
2*PI for normal-angle in the range [(3*PI)/2,2*PI) 


Using Enhanced X-Windows to Fill Areas 
To fill single rectanglar, polygon, or arc areas in a specified drawable, use the 
XFillRectangle, XFillPolygon, or XFillArc subroutine. To fill multiple areas in the specified 
drawable, use the XFillRectangles or XFillArcs subroutine. Each subroutine fills the 
specified area as if the four-point XFillPolygon subroutine were specified for each area. The 
following is an example of the four-point XFillPolygon subroutine: 


[x,y] [xtwidth, y] [x+twidth, ytheight] [x,ytheight] 


Each subroutine uses x and y coordinates, width and height dimensions, and the GC 
specified. 


The Xlib library also provides subroutines that can be used to fill the following: 
e A single rectangle or multiple rectangles 
e Asingle polygon 
e Asingle arc or multiple arcs 
Related Information 
The XPoint data structure. 


The XClearArea subroutine, XClearWindow subroutine, XCopyArea subroutine, 
XCopyPlane subroutine, XDrawArc subroutine, XDrawArcs subroutine, XDrawLine 
subroutine, XDrawLines subroutine, XDrawPoint subroutine, XDrawPoints subroutine, 
XDrawRectangle subroutine, XDrawRectangles subroutine, XDrawSegments 
subroutine, XFillArc subroutine, XFillArcs subroutine, XFillPolygon subroutine, 
XFillRectangle subroutine, XFillRectangles subroutine. 


Enhanced X-Windows Fonts Overview 


The Xlib library provides subroutines that enable you to use and manipulate fonts. A font is 
a graphical family or assortment of characters of a given size or style. 


The Xlib library provides subroutines that: 
e Load and free fonts 

e Obtain and free font names 

e Set and retrieve the font search path 

e Compute character string size 

e Return logical extents 

e Query character string sizes. 


The X Server loads fonts as they are requested by a program. The server can cache fonts 
for quick lookup. Fonts can be dealt with at several different levels. However, most 
applications simply use XLoadQueryFont to load a font and query the font metrics. 
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Characters in fonts are regarded as masks. Except for image text requests, the only pixels 
modified are pixels in which bits are on in the character. This means that it makes sense to 
draw text using stipples or tiles. For example, many menus gray-out unusable entries. 


Using Enhanced X-Windows to Draw Text Characters 


To draw 8-bit characters in the specified drawable, the text subroutine XDrawText uses the 
XTextitem data structure. 


To draw 2-byte characters in the specified drawable, the text subroutine XDrawText16 uses 
the XTextitem16 data structure. 


Using Enhanced X-Windows to Transfer Images Between Client and 


Server 


The Xlib library subroutines transfer images between a client and the server. Because the 
server may require diverse data formats, Enhanced X-Windows provides an image object 
that fully describes the data in memory and provides for basic operations on that data. The 
data should not be referenced directly, but rather through the image object. Some Xlib 
library implementations can deal with frequently used data formats by replacing routines in 
the procedure vector with special case routines. These operations include destroying the 
image, getting a pixel, storing a pixel, extracting a subimage of an image, and adding a 
constant to an image. 


Using Enhanced X-Windows to Manipulate Cursors 


Some subroutines load and change cursors associated with windows. Each window can 
have a different cursor defined for it. Whenever the pointer is in a visible window, it will be 
set to the cursor defined for that window. If no cursor is defined for that window, the cursor is 
the cursor defined for the parent window. 


For Enhanced X-Windows, a cursor consists of a cursor shape, mask, colors for the shape 
and mask, and a hot spot. Client programs refer to cursors by using cursor resource IDs. 


e The cursor pixmap determines the shape of the cursor. 


Enhanced X-Windows provides a set of standard cursor shapes in a special include file 
named cursorfont.h. Use this interface to customize your cursor for individual display. Use 
the XCreateFontCursor subroutine to customize your cursor from this special font, the 
XCreateGlyphCursor subroutine to customize your cursor from another font, and the 
XCreatePixmapCursor subroutine to create a cursor from two bitmaps. 


e The mask pixmap determines the bits that are modified by the cursor. 


e The colors determines the colors of ifie Snape and mask. [he initial colors of a cursor are 
black foreground and white background. Use the XRecolorCursor subroutine to change 
the color of the cursor. 


e The cursor hotspot defines the point on the cursor that is reported when a pointer event 
occurs. The hotspot in the XCreatePixmapCursor subroutine si specified by the x and y 
coordinate positions. 


Hardware can impose limitations on cursor sizes and masks. Enhanced X-Windows 
supports cursor masks and cursor colors. Use the XQueryBestCursor subroutine to find out 
what size cursors are possible. 


Related Information 


The XChar2b data structure, XFontStruct data structure, Xlmage data structure. 
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The XAddPixel subroutine, XCreateFontCursor subroutine, XCreateGlyphCursor 
subroutine, XCreatelmage subroutine, XDefineCursor subroutine, XDestroyimage 

- subroutine, XDrawText subroutine, XDrawText16 subroutine, XFreeCursor subroutine, 
XGetFontProperty subroutine, XGetlmage subroutine, XGetPixel subroutine, 
XGetSublimage subroutine, XLoadQueryFont subroutine, XPutIimage subroutine, 
XPutPixel subroutine, XQueryBestCursor subroutine, XQueryTextExtents subroutine, 
XQueryTextExtents16 subroutine, XRecolorCursor subroutine, XSublmage subroutine, 
XTextiltem Data Structure, XTextltem16 Data Structure, XUndefineCursor subroutine 


Enhanced X-Windows Predefined Property Subroutines 
Overview 


There are a number of predefined properties for common information usually associated with 
windows. The atoms for these properties are in the <K11/Xatom.h> file. 


The Xlib library subroutines perform predefined property operations used in communicating 
with window managers. 


Using Enhanced X-Windows to Communicate with Window Managers 
Clients require certain properties and subroutines to communicate with window managers 
effectively. Some of these properties have complex structures. For example, the data ina 
single property on the server has to be of the same format (8-bit, 16-bit, or 32-bit), and the 
structures of property types are not necessarily uniform. Therefore, the Xlib library provides 
Set and Get subroutines for properties with complex structures. 


These subroutines define, but do not enforce, minimal policy among window managers. It is 
encouraged that standard properties be used in creating window managers. However, 
additional properties may be defined for new window managers. 


In addition to Set and Get subroutines for individual properties, the Xlib library includes the 
XSetStandardProperties subroutine, which sets all or portions of the WM_NAME, 
WM_ICON_NAME, WM_NORMAL_HINTS, WM_HINTS, and WM_COMMAND properties. 
Applications are encouraged to provide the window manager more information than is 
possible with the XSetStandardProperties subroutine. To do so, the Set subroutines for the 
additional or specific properties required should be used. 


To work well with most window managers, an application should specify the name of the 
application, the name string for the icon, the command used to invoke the application, and 
the size and window manager hints. 


The Xlib library does not set defaults for the properties. The window manager determines 
the defaults which are based on the presence or absence of certain properties. All the 
properties are considered to be hints to a window manager. When implementing these hints, 
the window manager decides whether or not to use them. 


Predefined properties include the following: 


Name Type Format Description 

WM_NAME | STRING 8 Application name. 

WM_ICON_NAME STRING 8 Icon name. 

WM_NORMAL_HINTS WM_SIZE_HINTS 32 _ Size hints for a window in its 
normal state. (XSizeHints) 

WM_ZOOM_HINTS WN_SIZE_HINTS 32 _ Size hints for a zoomed 


window. (XSizeHints) 
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Name Type Format Description 


WM_HINTS WM_HINTS 32 Additional hints set by client for 
the window manager. 
(XWMHints) 

WM_COMMAND STRING 8 The command and arguments, 


separated by ASCII NULLS, 
used to invoke the application. 


WM_ICON_SIZE WM_ICON_SIZE 32 The window manager can set 
this property on the root 
window to specify the icon 
sizes it supports. (XlconSize) 


WM_CLASS STRING 32 Set by application programs to 
allow window and session 
managers to obtain the 
application resources from the 
resource database. 


WM_TRANSIENT_FOR WINDOW 32 Set by application programs to 
indicate to the window manager 
that a transient top-level 
window, such as a dialog box, 
is not really a full-fledged 
window. 


The atom names stored in the <X11/Xatom.h> file are named XA_PROPERTY_NAME. 


The Xlib library provides subroutines that can be used to set and get predefined properties. 
Calling the Set subroutine for a property with complex structure redefines all members in 
that property, even though only some of those members may have a specified new value. 
Simple properties for which the Xlib library does not provide a Set or Get subroutine can be 
set using the XChangeProperty subroutine. The values for simple properties can be 
retrieved using the XGetWindowProperty subroutine. 


Using Enhanced X-Windows to Set and Get Window Names 
The Xlib library provides subroutines to set and read the name of a window. The 
XStoreName subroutine assigns a name to a window. This window name is usually 
displayed by the window manager in a titlebar. The XFetchName subroutine gets the name 
of a window. It obtains a window name if the WM_NAME property is set. 


Using Enhanced X-Windows to Set and Get Icon Names 
The Xb library provides subroutines to set and get the name displayed in the icon of a 
window. These subroutines set and read the WM_ICON_NAME property. The 
XSeticonName subroutine sets the name displayed in the icon window. The 
XGeticonName subroutine gets the name set in the icon window by the XSetilconName 
subroutine. 


Using Enhanced X-Windows to Set and Get Window Manager Hints 
The Xlib library provides subroutines to set or get window manager hints. All the properties 
of a window are considered hints to a window manager. The window manager decides 
whether to implement these hints. — 


When setting and reading the WM_HINTS property, use the XWMHints data structure. 
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Using Enhanced X-Windows to Set and Get Window Manager Sizing 


Hints 


The Xlib library provides subroutines to set or get window sizing hints. All the properties of a 
window are considered hints to a window manager. The window manager decides whether 
to implement these hints. 


Use the XSizeHints data structure to set or get window sizing hints. 


Using Enhanced X-Windows to Set and Get Icon Sizing Hints 


Applications can cooperate with window managers by providing icons in sizes supported by 
a window manager. To communicate the supported icon sizes to the applications, a window 
manager should set the icon size property on the root window. To determine what icon sizes 
a window manager supports, applications should read the WM_ICON_SIZE property from 
the root window. 


Use the XiconSize data structure with the setting and getting icon sizing hints subroutines. 


Using Enhanced X-Windows to Set and Get the Class of a Window 


The Xlib library provides subroutines to set and get the class of a window with the 
WN_CLASS property. 


The name set in the WM_CLASS property may differ from the name set in the WM_NAME 
property. The WM_NAME property specifies what should be displayed in the title bar and, 
therefore, can contain temporal information (such as the name of a file currently in the 
buffer). The WM_CLASS property, however, specifies the formal name of the application that 
should be used when retrieving the application resources from the resource database. 


Use the XClassHint data structure to set and get the class of a window. 


Using Enhanced X-Windows to Set and Get the Transient Property 


An application can indicate to the window manager that a transient top-level window (for 
example, a dialog box) is operating on behalf of or is transient for another window. To do 
this, the application sets the WM_TRANSIENT_FOR property of the dialog box to be the 
window ID of its main window. 


Some window managers use this information to unmap dialog boxes of an application (for 
example, when the main application window is iconified). 


Related Information 


The XClassHint data structure, XlconSize data structure, XSizeHints data structure, 
XWMhints data structure. 


The <X11/Xatom.h> header file. 


The XChangeProperty subroutine, XFetchName subroutine, XGetClassHint subroutine, 
XGetlconName subroutine, XGetlconSizes subroutine, XGetNormalHints subroutine, 
XGetSizeHints subroutine, XGetTransientForHint subroutine, XGetWMHints subroutine, 
XGetWindowProperty subroutine, XGetZoomHints subroutine, XSetClassHint subroutine, 
XSetlconName subroutine, XSetlconSizes subroutine, XSetNormalHints subroutine, 
XSetSizeHints subroutine, XSetStandardProperties subroutine, XSetTransientForHint 
subroutine, XSetWMHints subroutine, XSetZoomHints subroutine, XStoreName 
subroutine. 
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Enhanced X-Windows Resource Manager Overview 


The resource manager is a special type of database manager. In most database systems, 
performing a query using an imprecise specification returns a set of records. The resource 
manager, however, allows you to specify a large set of values with an imprecise 
specification, to query the database with a precise specification, and to receive only a single 
value. The resource manager should be used by applications that need to know what the 
user prefers for colors, fonts, and other resources. 


For example, someone using your application may want to specify that all windows should 
have a blue background but that all mail-reading windows should have a red background. 
Presuming that all applications use the resource manager, a user can define this information 
using only two lines of specification. Your personal resource database usually is stored ina 
file and is loaded onto a server property when you login. This database is retrieved 
automatically by the Xlib library when a connection is opened. 


As an example of how the resource manager works, consider a mail-reading application 
called xmh. Assume that it is designed in such a manner that it uses a complex window 
hierarchy, all the way down to individual command buttons that can be actual small 
subwindows. These are often called objects or widgets. These user interface objects can be 
composed of other objects. Each user interface object can be assigned a name and a class. 
Fully qualified names or classes can have arbitrary numbers of component names, but a 
fully qualified name always has the same number of component names as a fully qualified 
class. This naming convention generally reflects the structure of the application as 
composed of these objects, starting with the application itself. 


For example, the xmh mail program has a name xmh and is one of a class of Mail 
programs. By convention, the first character of class components is capitalized while the first 
letter of name components is in lowercase. Each name and class also has an attribute, for 
example, foreground or font. |f each window is properly assigned a name and a class, it 
becomes easy for the user to specify attributes of any portion of the application. 


At the top level, the application might consist of a paned window (a window divided into 
several sections) named foc. One pane of the window is a button box window named 
buttons filled with command buttons. One of these command buttons is used to retrieve 
(include) new mail and has the name include. This window has a fully qualified name 
xmh.toc.buttons.include and a fully qualified class Xmh.VPaned.Box.Command. Its fully 
qualified names is the name of its parent, xmh.toc.buttons, followed by its name, include. 
Its class is the class of its parent window, Xmh.VPaned.Box, followed by its particular class, 
Command. The fully qualified name of a resource is the attribute name appended to the 
tuily qualified name of the object, and the fully qualified class is its class appended to the 
class of the object. 


The include button requires the following resources: 

e Title string 

e Font 

e Foreground and background color for its inactive state 
e Foreground and background color for its active state 


Each resource that this button needs is considered an attribute of the button and, as such, 
has a name and a class. For example, the foreground color for the button in its active state 
might be activeForeground and the class could be Foreground. 
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When an application searches for a resource (for example, a color), it passes the complete 
name and class of the resource to a lookup routine. Then, the resource manager returns the 
resource value and the representation type. 


The resource manager allows applications to store resources by an incomplete specification 
of name, class, and representation type, as well as to retrieve them given a fully qualified 
name and class. 


Using Enhanced X-Windows Resource Manager 
The definitions for the use of the resource manager are contained in the <X11/Xresource.h> 
header file. The Xlib library also uses the resource manager internally to allow for 
non-English language error messages. 


Database values consist of a size, an address, and a representation type. The size is 
specified in bytes. The representation type allows storage of data tagged by some 
application-defined type (for example, Font or Color). It has nothing to do with the C 
language data type or with its class. 


Most uses of the resource manager involve defining names, classes, and representation 
types as string constants. However, always referring to strings in the resource manager can 
be slow, because it is used so heavily by some toolkits. To solve this problem, a shorthand 
name for a string is used in place of the full name of the string in many of the resource 
manager subroutines. Simple comparisons can be performed rather than string 
comparisons. The short name for a string is quark. The quark type is XrmQuark. You may 
want to allocate a quark that has no string equivalent on some occasions. (A quark is to a 
string what an atom is to a property name in the server, but the use of a quark is local to 
your application.) 


Each name, class, and representation type is defined as an XrmQuark: 


typedef int XrmQuark, *XrmQuarkList; 
typedef XrmQuark XrmName; 

typedef XrmQuark XrmClass; 

typedef XrmQuark XrmRepresentation; 


Lists are represented as null-terminated arrays of quarks. The size of the array must be 
large enough for the number of components used. 


typedef XrmQuarkList XrmNameList; 
typedef XrmQuarkList XrmClassList; 


Using Enhanced X-Windows to List Resource Manager Matching Rules 
The algorithm for determining which resource name matches a given query is the heart of 
the database. Resources are stored with only partially specified names and classes, using 
pattern matching constructs. An asterisk (*) is used to represent any number of intervening 
components, including none. A period (.) is used to separate immediately adjacent 
components. All queries fully specify the name and class of the resource needed. A trailing 
asterisk or period is not removed. The library supports 100 components in a name ora 
class. The lookup algorithm searches the database for the name that most closely matches 
(is most specific) to this full name and class. The rules in order of precedence for a match 
are: 


1. The attribute of the name and class must match. For example, queries for 


aixterm.scrollbar.background (name ) 
AIXTerm.Scrollbar.Background (class) 


will not match the database entry 


aixterm.scrollbar:on 
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2. Database entries.with a name or class prefixed by a period (.) are more specific than 
those prefixed by an asterisk (*). For example, aixterm.geometry is more specific 
than aixterm*geometry. 


3. Names are more specific than classes. For example, *scrollbar.background is 
more specific than *Scrollbar.Background. 


4. Aname or class is more specific than an omission. For example, 
Scrollbar*Background is more specific than *Background. 


5. Left components are more specific than right components. For example, 
*vt100*background is more specific than *scrollbar*background for the query 
-vt100.scrollbar.background. 


6. If neither a period (.) nor an asterisk (*) is specified at the beginning, a period is implicit. 
For example, aixterm. background is identical to .aixterm. background. 


Names and classes can be mixed. As an example of these rules, assume the following user 
specification: 


xmh*background: red 
*command.font: 8x13 
*command.background: blue 
*Command.Foreground: green 


xmh.toc*Command.activeForeground: black 

A query for the name 
xmh.toc.messagefunctions.include.activeForeground 
and class 

Xmh.VPaned.Box.Command. Foreground 

would match 

xmh.toc*Command.activeForeground 

and return black. However, it also matches 
*Command.Foreground. 


Using the precedence algorithm described above, the resource manager would return the 
value specified by xmh.toc*Command.activeForeground. 


Using Enhanced X-Windows to Store Information Into a Resource 


Database 


The Xlib library provides subroutines to store resources into the database. The 
XrmPutResource and XrmQPutResource subroutines take a partial resource specification, 
a representation type, and a value. This value is copied into the specified database. To add 
a resource that is specified as a string, use the XrmPutResource subroutine. To add a 
string resource using quarks as a specification, use the XrmQPutResource subroutine. To 
add a resource entry that is specified as a string that contains both a name and a value, use 
the XrmPutLineResource subroutine. 


Using Enhanced X-Windows to Retrieve Information from a Resource 


Database 


The Xlib library provides subroutine to retrieve a resource from a specified resource 
database. The XrmGetResource and XrmQGetResource subroutines take a fully qualified 
name and class pair, a destination resource representation, and the address of a value (size 
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and address pair). The value and the returned type point into database memory that should 
not be modified. 


The database only frees or overwrites entries on the XrmPutResource, 
XrmQPutResource, or XrmMergeDatabases subroutines. A client that is not storing new 
values and is not merging the database should be safe using the address passed back at 
any time until it exits. If a resource is found, the XrmGetResource and XrmQGetResource 
subroutines return the value of True. 


The Xlib library also provides subroutines to search and return lists of resource database 
levels, as well as to combine, retrieve and store databases. 


Most applications and toolkits do not make random probes into a resource database to fetch 
resources. The X Toolkit access pattern for a resource database is quite stylized. A series of 
probes (from 1 to 20 in number) are made with only the last name-class pair differing in each 
probe. The XrmGetResource subroutine is at worst a 2**" algorithm, where nis the length 
of the name-class pair list. This can be improved upon by the application programmer by 
prefetching a list of database levels that might match the first part of a name-class pair list. 


Using Enhanced X-Windows to Parse Command Line Options 
The Xlib library provides a subroutine to load a resource database from a C language 
command line. The XrmParseCommand subroutine can be used to parse the command 
line arguments to a program and modify a resource database with selected entries from the 
command line. 


Related Information 
The XrmOptionDescList data structure, XrmValue data structure. 


The <X11/Xresource.h> header file. 


The Xpermalloc subroutine, XrmGetFileDatabase subroutine, XrmGetResource 
subroutine, XrmGetStringDatabase subroutine, XrmMergeDatabases subroutine, 
XrmParseCommand subroutine, Xrmlnitialize subroutine, XrmPutFileDatabase 
subroutine, XrmPutLineResource subroutine, XrmPutResource subroutine, 
XrmPutStringResource subroutine, X*mQGetResource subroutine, Xr*mQGetSearchList 
subroutine, XrmQGetSearchResource subroutine, XrmQPutResource subroutine, 
XrmQPutStringResource subroutine, XrmQuarkToString subroutine, 

XrmString ToBindingQuarkList subroutine, XrmString ToQuark subroutine, 
XrmStringToQuarkList subroutine, XrmUniqueQuark subroutine. 


Enhanced X-Windows Context Manager Overview 


The context manager provides a way of associating data with a window in your program. 
The context manager is local to your program; the data is not stored in the server ona 
property list. Any data in any number of pieces can be associated with a window, and each 
piece of data has a type associated with it. The context manager requires the window ID and 
type to store or retrieve data. 


Essentially, the context manager can be viewed as a two-dimensional, sparse array. One | 
dimension is subscripted by the window ID and the other by a context type field. Each entry 
in the array contains a pointer to the data. 


The Xlib library provides context management subroutines to save and get data values, 
delete entries, and create a unique context type. The symbols used are in the <X11/Xutil.h> 
header file. 
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Related Information 
The <X11/Xutil.h> header file. 


The XDeleteContext subroutine, XFindContext subroutine, XSaveContext subroutine, 
XUniqueContext subroutine. 


Enhanced X-Windows Window Information Subroutines 
Overview 


After the display is connected to the X Server and a window is created, use Xlib window 
information subroutines to perform the following tasks: 


e Obtain information about a window 
e Manipulate property lists 
e Obtain and change window properties 


e Manipulate window selection. 


Defining Enhanced X-Windows Coordinates 
Like the display screen, each window has its own xy coordinate system with the origin at the 
upper-left hand corner. The x axis is horizontal (left to right); the y axis is vertical (top to 
bottom). Each addressable point on the screen is called a pixel and corresponds to one xy 
point in the coordinate system. Because each window has its own coordinate system, 
operations within windows can be insensitive to the window position on the screen. 


The origin of a window is inside the border, if it has one, and window size is always the 
usable number of pixels within the border. The window border is maintained by the X Server, 
and output to the window is clipped so as not to extend into the border. 


Obtaining Enhanced X-Windows Window Information 
Xlib subroutines obtain information about the window tree, the current attributes of a 
window, its current geometry, or the current pointer coordinates. Because these subroutines 
are used primarily by window managers, they return a status to indicate if the window still 
exists. 


The XGetWindowAttributes subroutine returns the current attributes for the specified 
window to an XWindowéAitiributes structure. 


Obtaining Enhanced X-Windows Environment Defaults 


A program often needs a variety of options in the X environment (for example, fonts, colors, 
mouse, background, text, and cursor). Specifying these options to run on the command line 
is inefficient and unmanageable because individual users have different tastes with regard to 
window appearance. The XGetDefault subroutine facilitates finding the default fonts, colors, 
anc other environment options favored by a particular user. 


Defaults are usually loaded into the resource manager property on the root window during 
login. The XGetDefault subroutine merges additional defaults from a file in the user’s home 
directory. The XGetDefault subroutine provides a simple interface for clients. 


Using Enhanced X-Windows Properties and Atoms 
A property is a collection of names, typed data. The window system has a a set of 
predefined properties, such as the name of a window and size hints. 
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Each property has a name which is an !SO Latin—1 string. For each named property, a 
unique identifier (atom) is associated with it. Users can define any other arbitrary information 
and can associate this information with a window. (Use XinternAtom to define new 
properties or to obtain the atom for new properties.) 


A property also has a type, for example, a string or an integer. These types are also 
indicated using atoms. Therefore, arbitrary new types can be defined. The type of a property 
is defined by other properties, which allows for arbitrary extension. Use the properties 
mechanism to communicate other information between applications. 


A property is stored in one of several possible formats. The X Server can store the 
information as 8-bit, 16-bit, or 32-bit quantities. This flexibility permits the X Server to 
present the data in the byte order that the client expects. 


Certain properties are predefined in the server for commonly used subroutines. The atoms 
for these properties are defined in <X11/Xatom.h>. To avoid name clashes with user 
symbols, the macro name for each atom has the XA_ prefix added. 


Atoms occur in five distinct name spaces within the protocol: selections, property names, 
property types, font properties and types of ClientMessage events (none are built into the 
X Server). 


Any particular atom can have some client interpretation within each of the name spaces. The 
built-in selection properties, which name properties, are PRIMARY and SECONDARY. 


The built-in property names are: 


CUT_BUFFERO RGB_GREEN_MAP WM_CLIENT_MACHINE 
CUT_BUFFER1 RGB_RED_MAP WM_COMMAND 
CUT_BUFFER2 RGB_BEST_MAP WM_HINTS 
CUT_BUFFER3 RGB_BLUE_MAP WM_ICON_NAME 
CUT_BUFFER4 RGB_DEFAULT_MAP WM_ICON_SIZE 
CUT_BUFFER5 RGB_GRAY_MAP WM_NAME 
CUT_BUFFER6 RESOURCE_MANAGER WM_NORMAL_HINTS 
CUT_BUFFER7 WM_CLASS WM_ZOOM_HINTS 


WM_TRANSIENT_FOR 
The built-in property types are: 


ARC DRAWABLE RGB_COLOR_MAP 
ATOM FONT STRING 

BITMAP INTEGER VISUALID 
CARDINAL PIXMAP WINDOW 
COLORMAP POINT WM_HINTS 
CURSOR RECTANGLE WM_SIZE_HINTS 
The built-in font property types are: 

MIN_SPACE UNDERLINE_POSITION QUAD_WIDTH 
NORM_SPACE UNDERLINE_THICKNESS WEIGHT 
MAX_SPACE FONT_NAME POINT_SIZE 
END_SPACE FULL NAME RESOLUTION 
SUPERSCRIPT_X STRIKEOUT_DESCENT COPYRIGHT 
SUPERSCRIPT_Y STRIKEOUT_ASCENT NOTICE 
SUBSCRIPT_X ITALIC_ANGLE FAMILY_NAME 
SUBSCRIPT_Y X_HEIGHT CAP_HEIGHT 


Obtaining and Changing Enhanced X-Windows Window Properties 


You can attach a property list to every window. Each property has a name, a type, anda 
value. The value is an array of 8-bit, 16-bit, or 32-bit quantities, whose interpretation is left to 
the clients. 
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You can obtain, rotate, or change a window property. In addition, the Xlib library provides 
subroutines for predefined property operations. 


Using Enhanced X-Windows Window Selections 
Selection is one method of exchanging data between applications. By using the property 
mechanism, applications can exchange data of arbitrary types and can negotiate the type of 
data to be exchanged. A selection can be thought of as an indirect property with a dynamic 
type. Rather than having the property stored in the X Server, the property is maintained by 
some client (the owner). A selection is global in nature. It belongs to the user but is 
maintained by the clients, rather than being private to a particular window subhierarchy or a 
particular set of clients. 


The Xlib library subroutines set, get, or convert window selection. These subroutines allow 
applications to implement the notion of current selection, which requires that applications be 
notified when they no longer own the selection. Applications that support selection often 
highlight the current selection. To unhighlight the selection, applications must be able to be 
informed when some other application acquires the selection. 


When a client asks for the contents of a selection, it specifies a selection target type. This 
target type can be used to control the transmitted representation of the contents. For 
example, if the selection is “the last thing the user clicked on”, and currently an image, then 
the target type might specify whether the contents of the image should be sent in XYFormat 
or ZFormat. 


The target type can also be used to control the class of contents transmitted, for example, 
asking for the page format (fonts, line spacing, indentation, and other page format 
specifications) of a paragraph selection, not the text of the paragraph. The target type can 
also be used for other purposes. The semantics are not constrained by the protocol. 


Related Information 
The XWindowAttributes data structure. 


The XChangeProperty subroutine, XConvertSelection subroutine, XDeleteProperty 
subroutine, XGetAtomName subroutine, XGetDefault subroutine, XGetGeometry 
subroutine, XGetSelectionOwner subroutine, XGetWindowAttributes subroutine, 
XGetWindowProperty subroutine, XinternAtom subroutine, XListProperties subroutine, 
XQueryPointer subroutine, XQueryTree subroutine, XRotateWindowProperties 
subroutine, XSetSelectionOwner subroutine. 


Enhanced X-Windows Window Manaaer Suhro 
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The Xlib library window manager subroutines allow you to create a window manager 
application that can: 


e Control the lifetime of a window 
e Manipulate the pointer 
e Manipulate keyboard settings and the keyboard encoding 
e Control host access 
Using Enhanced X-Windows to Control the Lifetime of a Window 
The save-set of a window manager is a list of other client windows that should not be 


- destroyed if the client windows are inferior windows of the window manager windows at 
connection close. To allow an application window to survive when a window manager fails, 
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the Xlib library provides the save-set subroutines that change a window manager save-set, 
add a window to a window manager save-set, or remove a subwindow from a window 
manager save-set. 


Some subroutines are used to control the longevity of subwindows that are normally 
destroyed when the parent is destroyed. For example, a window manager that wants to add. 
decoration to a window by adding a frame might reparent an application window. When the 
frame is destroyed, the application window should not be destroyed but returned to its 
previous place in the window hierarchy. 


The X Server automatically removes windows from the save-set when they are destroyed. If 
a save-set window is an inferior of a window manager window, the save-set window is 
reparented to the closest ancestor so that the save-set window is not an inferior window of a 
window created by the window manager. If the save-set window is unmapped, a 
MapWindow request is performed on it. After the save-set list is processed, all windows 
created by the window manager are destroyed. For each nonwindow resource created by 
the window manager, the appropriate Free request is performed. All colors and colormap 
entries allocated by the window manager are freed. 


Using Enhanced X-Windows to Grab the Pointer 


The Xlib library subroutines control input from the pointer, which is usually a mouse. The 
window manager uses these facilities to implement certain styles of user interface. Some 
applications may use these facilities for special purposes. 


Usually, the X Server delivers keyboard and mouse events as soon as they occur to the 
appropriate client, depending upon the window and input focus. The X Server provides 
sufficient control over event delivery to allow window managers to support various styles of 
user interface. Many of the styles depend upon synchronous delivery of events. The delivery 
of pointer and keyboard events can be controlled independently. 


When mouse buttons or keyboard keys are grabbed, events are sent to the grabbing client 
rather than the normal client. If the keyboard or pointer is in asynchronous mode, further 
mouse and keyboard events continue being processed. If the keyboard or pointer is in 
synchronous mode, no further events are processed until the grabbing client allows them to 
be processed. The keyboard or pointer is considered frozen during this interval. The 
triggering event can also be replayed. 


There are two kinds of grabs: an active grab and a passive grab. 
Active grab — This occurs when a single client grabs the keyboard or pointer explicitly. 


Passive grab This occurs when clients grab a particular keyboard key or pointer button in 
a window. Passive grabs are convenient for implementing reliable pop-up 
menus. 


The grab activates when the key or button is actually pressed. For example, you can 
arrange that the pop-up is mapped before the up pointer button event occurs by grabbing a 
button requesting synchronous behavior. The down event triggers the grab and freezes 
further processing of pointer events until you have the chance to map the pop-up window. 
You can then allow further event processing. The up event is then correctly processed 
relative to the pop-up window. 


For many operations, there are subroutines that take a time argument. The X Server 
includes a timestamp in various events. One special time called CurrentTime represents the 
current server time. The X Server maintains the time when the input focus was last changed 
and the time of the server when the client last performed an active grab, when the keyboard 
was last grabbed, or when a selection was last changed. This allows you to specify that your 
request not occur if some other application has in the meantime taken control of the 
keyboard, pointer, or selection. 
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Using Enhanced X-Windows to Grab the Server 
Some Xlib library subroutines grab and ungrab the server. These suroutines can be used to 
control processing of output on other connections by the window system server. No 
processing of requests or close downs on any other connection occurs while the server is 
grabbed. If a client closes its connection to the server, the client automatically ungrabs the 
server. Grabbing the server is highly discouraged unless it is absolutely necessary. 


Using Enhanced X-Windows to Manipulate Keyboard Settings 
With Xlib library subroutines, you can change the keyboard control, obtain a list of the 
auto-repeat keys, turn keyboard auto-repeat on or off, ring the bell, set or obtain the pointer 
button or keyboard mapping, and obtain a bit vector for the keyboard. 


You can set many of these options to your preference. The default values for many of these 
subroutines are determined by command line arguments to the X Server. Not all 
implementations can actually control all of these parameters. 


The XKeyboardControl data structure is used in subroutines that change control from a 
keyboard. 


The XKeyboardState data structure is used in subroutines that return the current control 
values for the keyboard. 


Using Enhanced X-Windows to Manipulate Keyboard Encoding 
A Keycode represents a physical (or logical) key. Keycodes lie in the inclusive range [8,255]. 
A keycode value carries no intrinsic information. The mapping between keys and keycodes 
cannot be changed. 


A Keysym is an encoding of a symbol on the cap of a key. The set of defined Keysyms 
include: 


e the ISO Latin character sets (1-4) 
e Katakana 

e Arabic 

e Cyrillic 

e Greek 

e Technical 

e Special 

° Pubiishing 

e APL 

e Hebrew 

e aspecial miscellany of keys found on keyboards (such as RETURN, HELP, and TAB) 


To the extent possible, these sets are derived from international standards. The list of 
defined symbols is in the <X11/keysymdef.h> header file. If you must use Keysyms not in 
the ISO Latin 1-4, Greek, and miscellany classes, you may have to define a symbol for those 
sets. Most applications usually include only <X11/keysym.h>, which defines symbols for 
ISO Latin 1-4, Greek, and miscellany. 


A list of Keysyms is associated with each Keycode. The length of the list can vary with each 
Keycode. The list is intended to convey the set of symbols on the corresponding key. By 
convention, if the list contains a single Keysym and if that Keysym is alphabetic and case 
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distinction is relevant for it, then it should be treated as equivalent to a two-element list of the 
lowercase and uppercase Keysyms. For example, if the list contains the single Keysym for 
uppercase A, the client should treat it as if it were a pair with lowercase a as the first Keysym 
and uppercase A as the second Keysym. 


For any Keycode, the first Keysym in the list should be chosen as the interpretation of a 
KeyPress when no modifier keys are down. 


The second Keysym in the list normally should be chosen when the Shift modifier is on, or 
when the Lock modifier is on and Lock is interpreted as ShiftLock. 


When the Lock modifier is on and is interpreted as CapsLock, it is suggested that the Shift 
modifier first be applied to choose a Keysym, but if that Keysym is lowercase alphabetic, the 
corresponding uppercase Keysym should be used instead. 


Other interpretations of CapsLock are possible; for example, it may be viewed as equivalent 
to ShiftLock, but only applying when the first Keysym is lowercase alphabetic and the 
second Keysym is the corresponding uppercase alphabetic. No interpretation of Keysyms 
beyond the first two in a list is suggested here. No spatial geometry of the symbols on the 
key is defined by their order in the Keysym list although a geometry might be defined on a 
vendor-specific basis. The X Server does not use the mapping between Keycodes and 
Keysyms. Rather, it stores the mapping for reading and writing by clients. 


The XLookupString subroutine performs simple translation of a key event to an ASCII 
~ String. 

The XModifierKeymap data structure is used by subroutines that modify the keyboard 

mapping. 


Using Enhanced X-Windows to Control Host Access 
Enhanced X-Windows does not provide any protection on a per-window basis. If you find out 
the ID of a resource, you can manipulate it. To provide some minimal level of protection, 
however, connections are permitted only from systems you trust. This is adequate on 
single-user workstations, but breaks down on time-sharing machines. 


The initial set of hosts allowed to open connections consists of: 
e The host the window system is running on. 


e On AiX-based systems, the hosts listed in the /etc/X?.hosts file. The “?” indicates the 
number of the display. This file should consist of host names separated by newlines. 


If a host is not in the access control list when the access control mechanism is enabled and 
if the host attempts to establish a connection, the server refuses the connection. To change 
the access list, the client must reside on the same host as the server and/or must have been 
granted permission in the initial authorization at connection setup. The initial access control 
list can be specified by providing a file that the server can read at startup and reset time. 


To add, get, or remove hosts, the host access control subroutines use the XHostAddress 
data structure. 


Related Information 
The <X11/keysymdef.h> header file, <X11/keysym.h> header file. 


The /etc/X?.hosts file. 


The XHostAddress data structure, XKeyboardControl data structure, XKeyboardState 
data structure, XModifierKeymap data structure. 


The XAddHost subroutine, XAddHosts subroutine, XAddToSaveSet subroutine, 
XAllowEvents subroutine, XAutoRepeatOn subroutine, XBell subroutine, 
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XChangeActivePointerGrab subroutine, XChangeKeyboardControl subroutine, 
XChangeKeyboardMapping subroutine, XChangeSaveSet subroutine, 
XDeleteModifiermapEntry subroutine, XFreeModifiermap subroutine, 
XGetKeyboardControl subroutine, XGetKeyboardMapping subroutine, 
XGetModifierMapping subroutine, XGetPointerMapping subroutine, XGrabButton 
subroutine, XGrabKey subroutine, XGrabKeyboard subroutine, XGrabPointer subroutine, 

. XGrabServer subroutine, XInsertmodifiermapEntry subroutine, XListHosts subroutine, 
XLookupString subroutine, XNewModifiermap subroutine, XQueryKeymap subroutine, 
XRemoveFromSaveSet subroutine, XRemoveHost subroutine, XRemoveHosts 
subroutine, XSetModifierMapping subroutine, XSetPointerMapping subroutine, 
XUngrabButton subroutine, XUngrabkey subroutine, XUngrabKeyboard subroutine, 
XUngrabPointer subroutine, XUngrabServer subroutine. 


Enhanced X-Windows Window Subroutines Overview 


in Enhanced X-Windows, a window is a rectangular area on the screen that lets you view 
graphical output. Client applications can display overlapping and nested windows on one or 
more screens that are driven by X Servers on one or more systems. Use the XOpenDisplay 
subroutine to open a display. 


Defining Enhanced X-Windows Visual Types 
On some high-end displays, color resources can be used in several ways. For example, you 
can use the display as a 12-bit display with arbitrary mapping of pixel to color (pseudo-color) 
or aS a 24-bit display with 8 bits of the pixel dedicated for red, green, and blue. These 
different ways of using visual aspects are called Visuals. For example, 


e The screen can be color or grayscale. 


e The screen can have a colormap that is writable or read-only. 


e Ascreen can also have a colormap whose indices are decomposed into separate RGB 
pieces, provided one is not on a grayscale screen. The following table shows the color or 
grayscale of a colormap: 









aa Read-Only Read—Write Read-Only Read—Write 
Undecomposed Static Pseudo Static Gray 
Colormap Color Color Gray Scale 





Decomposed True - Direct 
Colormap Color Color 


Determining the Appropriate Enhanced X-Windows Visual 
For each screen, a list of valid visual types can be supported at different depths of the 
display. The Xlib library uses the XVisuallnfo data structure to determine which visual to 
use in the application. 





Defining Enhanced X-Windows Window Attributes 
All InputOutput windows have a border width of zero or more pixels, an optional 
background, an input mask, an event suppression mask, and a property list. The window 
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border and background can be a solid color or a pattern, which is called a tile. All windows, 
except the root window, have a parent window and are clipped by the parent window. 


e Ifa window is stacked on top of another window, the top window obscures the lower 
window, not allowing it to accept input. Input events, such as pointer motion events, are 
not generated for the obscured area of the lower window. . 


e If the top window has a background, the top window obscures the lower window, not 
allowing it to have output. Output attempts to the obscured area of the lower window 
produce no result. 


Windows with a class of InputOnly are used to control input events in situations where 
full-fledged windows are not necessary. InputOnly windows are used to control input events 
in situations where InputOutput windows are not necessary. InputOnly windows are 
invisible and can only be used to control such things as cursors, input event generation and 
grabbing. They cannot be used for any graphics events. InputOnly windows cannot have 
InputOutput windows as inferiors. Both InputOnly and InputOutput windows have the 
following attributes: 


e win_gravity 

e event_mask 

e do_not_propagate_mask 

e override_redirect 

e cursor 

If other fields are defined for an InputOnly window, a BadMatch error is generated. 


Windows have borders of a programmable width and pattern, as well as a background 
pattern or tile. Pixels can be used for solid colors. Refer to the window in a program by using 
the resource ID of type Window. The background and border pixmaps can be destroyed 
immediately after creating the window if no further explicit references are made.The 
background of a window can be a solid color or a pattern. 


e Ifthe pattern is relative to the parent window, the pattern is shifted appropriately to match 
the parent window. 


e Ifthe pattern is absolute, it is positioned in the window independently of the parent 
window. 


When an application first creates a window, it is not visible (unmapped). Unmapped windows 
are invisible, and output to an unmapped window is discarded. When a window is eventually 
mapped to the screen with the XMapWindow subroutine, the X Server generates an 
exposure event for the window if backing store has not been maintained. 


A window manager can override the size, border width, and style of a window specified in 
your program. You should be prepared to use the actual size and position of the top window, 
which is reported as an event when the window is first mapped. A client program should not 
resize itself without command input. Instead, the client program should use the space 
specified. lf the space specified is insufficient, the client program can request a resize of the 
window. Only the border of the top-level windows can be changed by window managers. 


Creating Enhanced X-Windows Windows 
The Xlib library provides basic ways for creating windows. When you create top-level 
windows or direct children of the root window, the following should be observed to ensure 
that applications interact properly across differing styles of window management. 
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e Allow the window manager to determine the size or placement of your top-level windows. 
Provide the window manager with some standard information or hints with the various 
window manager hints subroutines. 


e An application, by interpreting the first exposure event, must be able to deal with 
whatever size window it gets, even if this means that the application just prints a 
message, such as “Please make me bigger’, in the window. 


e An application should be able to resize or move the children of its top-level window as 
necessary. An application should only resize or move its top-level window in direct 
response to a user request. Otherwise, the request may fail. 


e Applications should not be written to assume control of the window manager. 


e The application should set standard window properties for the top-level window before 
mapping it. To set standard window properties for a top-level window, use the 
XSetStandardProperties subroutine. 


Use the XCreateWindow and XCreateSimpleWindow subroutines to create an unmapped 
subwindow for a specified parent window. 


e The XCreateWindow subroutine allows you to set specific window attributes when you 
create the window. 


e The XCreateSimpleWindow subroutine creates a window that inherits its window 
attributes from the parent window. 


InputOnly windows cannot be used for graphics requests, exposure processing, and 
VisibilityNotify events. An InputOnly window cannot be used as a source or destination 
drawable for graphics requests. 


Destroying Enhanced X-Windows Windows 
Enhanced X-Windows. also allows you to destroy windows and subwindows. You can 
destroy a window or destroy all subwindows of a window. If a window is destroyed, it should 
not be referenced by another subroutine. If you specify that a root window be destroyed, no 
windows are actually destroyed. By default, windows are destroyed when a connection to 
the X Server is closed. 


Mapping Enhanced X-Windows Windows 
A window is considered mapped if an XMapWindow call is made on the window. The 
window may not be visible on the screen for one of the following reasons: 


e The window is nhiaaen by anoiner opaque sibling window. 
e One of the window ancestors is not mapped. 
e The window is entirely clipped by an ancestor. 


A window manager can control the placement of subwindows. If . 
SubstructureRedirectMask has been selected by a window manager on a parent window 
(usually a root window), a map request initiated by other clients on a child window is not 
performed, and the window manager is sent a MapRequest event. 


If the override_redirect field on the child is set to True (usually only on pop-up menus), the 
map request is performed. 


A tiling window manager can reposition and resize other client windows and then map the 
window at its final location. Only one client at a time can select SubstructureRedirectMask. 


Similarly, a single client can select ResizeRedirectMask on a parent window. Any attempt to 
resize the window is suppressed, and the client, which is usually a window manager, 
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receives a ResizeRequest event. These mechanisms allow arbitrary placement policy to be 
enforced by an external window manager. 


Exposure events are generated for the window when part or all of it becomes visible on the 
screen. A client will only receive the exposure events if it requests these events with 
XSelectinput. Windows retain their position in the stacking order when unmapped. 


Configuring Enhanced X-Windows Windows 
The Xlib library subroutines can move a window, resize a window, move and resize a 
window, or change the border width of a window. The most general interface to configuring 
windows, the XConfigureWindow subroutine, uses the XWindowChanges data structure. 


Related Information 
The XSetWindowaAittributes data structure, XVisuallnfo data structure, 
XWindowChanges data structure. 


The XCirculateSubwindows subroutine, XCirculateSubwindowsDown subroutine, 
XCirculateSubwindowsUp Subroutine, XConfigureWindow subroutine, 
XCreateSimpleWindow subroutine, XCreateWindow subroutine, XDestroySubwindows 
subroutine, XDestroyWindow subroutine, XGetVisuallnfo subroutine, XLowerWindow 
subroutine, XMapRaised subroutine, XMapSubwindows subroutine, XMapWindow 
subroutine, XMatchVisualinfo subroutine, XMoveWindow subroutine, 
XMoveResizeWindow subroutine, XRaiseWindow subroutine, XResizeWindow 
subroutine, XRestackWindows subroutine, XSetStandardProperties subroutine, 
XSetWindowBorderWidth subroutine, XUnmapSubwindows subroutine, 
XUnmapWindow subroutine, XVisuallDFromVisual subroutine. 
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List of Enhanced X-Windows Xlib Data Structures 


The XAIXDeviceMappingEvent data structure 
The XVisuallnfo data structure 

The XSetWindowaAittributes data structure 
The XWindowChanges data structure 

The XWindowAttributes data structure 
The XColor data structure 

The XGCValues data structure 

The XStandardColormap data structure 
The XSegment data structure 

The XRectangle data structure 

The XPoint data structure 

The XArc data structure 

The XCharStruct data structure 

The XFontProp data structure 

The XChar2b data structure 

The XFontStruct data structure 

The XTextltem data structure 

The XTextitem16 data structure 

The Xlmage data structure 

The XKeyboardControl data structure 

The XKeyboardState data structure 

The XModifierKeymap data structure 

The XHostAddress data structure 

The XAnyEvent data structure 

The XEvent data structure 

The XButtonPressedEvent data structure 
The XButtonReleasedEvent data structure 
The XKeyPressedEvent data structure 
The XKeyReleasedEvent data structure 
The XPointerMovedEvent data structure 
The XCrossingEvent data structure 

The XEnterWindowEvent data structure 
The XLeaveWindowEvent data structure 
The XFocusinEvent data structure 

The XFocusOutEvent data structure 

The XKeymapEvent data structure 

The XExposeEvent data structure 

The XGraphicsExposeEvent data structure 
The XNoExposeEvent data structure 

The XCirculateEvent data structure 

The XConfigureEvent data structure 

The XCreateWindowEvent data structure 
The XDestroyWindowEvent data structure 
The XGravityEvent data structure 

The XMapEvent data structure 

The XMappingEvent data structure 

The XReparentEvent data structure 

The XUnmapEvent data structure 

The XVisibilityEvent data structure 

The XCirculateRequestEvent data structure 
The XConfigureRequestEvent data structure 
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The XMapRequestEvent data structure 
The XResizeRequestEvent data structure 
The XColormapEvent data structure 

The XClientMessageEvent data structure 
The XPropertyEvent data structure 

The XSelectionClearEvent data structure 
The XSelectionRequestEvent data structure 
The XSelectionEvent data structure 

The XErrorEvent data structure 

The XWMHints data structure 

The XSizeHints data structure 

The XiconSize data structure 

The XClassHint data structure 

The XrmValue data structure 

The XrmOptionDescList data structure 


XVisualinfo Data Structure 


#define VisualNoMask 0x0 
#define VisualIDMask Oxl 
#define VisualScreenMask 0x2 
#define VisualDepthMask 0x4 
#define VisualClassMask 0x8 
#define VisualRedMaskMask 0x10 
#define VisualGreenMaskMask 0x20 
#define VisualBlueMaskMask 0x40 
#define VisualColormapSizeMask 0x80 
#define VisualBitsPerRGBMask 0x100 
#define VisualAllMask Ox1FF 


typedef struct { 
Visual *visual; 
VisualID visualid; 
int screen; 
unsigned int depth; 
int class; 


unsigned long red_mask; 
unsigned long green_mask; 
unsigned long blue_mask; 
int colormap_size; 
int bits _per_rgb; 

} XVisualinfo; 


The fields of the XVisuallnfo data structure are as follows: 


bits_per_rgb 


Specifies the log base 2 of the approximate number of distinct color 


values (individually) of red, green, and blue (RGB). Actual RGB values 
are unsigned 16-bit numbers. 


blue_mask Defined only for DirectColor and TrueColor. Each mask has one 
contiguous set of bits with no intersections. 
class Specifies the possible visual classes of the screen. It can be one of the 


following: PseudoColor, GrayScale, DirectColor, TrueColor, 
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colormap_size 
depth 
green_mask 
red_mask 


screen 


StaticColor, or StaticGray. Conceptually, as each pixel is read out of 
video memory, it goes through a lookup stage by indexing into a 
colormap. Colormaps can be manipulated arbitrarily on some 
hardware, in a limited way on other hardware, and not at all on other — 
hardware. The visual types affect the colormap and the RGB values in 
the following ways: 


PseudoColor A pixel value indexes a colormap to produce 
independent RGB values, and the RGB values can 
be changed dynamically. 


GrayScale A pixel value indexes a colormap to produce 
independent RGB values, and the RGB values can 
be changed dynamically, except that the primary 
that drives the screen is not defined. Therefore, the 
client should always store the same value for red, 
green, and blue in the colormaps. 


DirectColor A pixel value is decomposed into separate RGB 
subfields, and each subfield separately indexes the 
colormap for the corresponding value. The RGB 
values can be changed dynamically. 


TrueColor A pixel value is decomposed into separate RGB 
subfields, except that the colormap has predefined 
read-only RGB values. These values are 
server-dependent, but provide linear or near-linear 
ramps in each primary. 


StaticColor A pixel value indexes a colormap to produce 
independent RGB values, and the RGB values can 
be changed dynamically, except that the colormap 
has predefined read-only server-dependent RGB 
values. 


StaticGray A pixel value indexes a colormap to produce 
independent RGB values, and the RGB values can 
be changed dynamically, except that the red, green, 
and blue values are equal for any single pixel value 
ihai results in snades of gray. StaticGray with a 
two-entry colormap can be considered 
monochrome. 


Defines the number of available colormap entries in a newly created 
colormap. For DirectColor and TrueColor, this number is the size of 
an individual pixel subfield. 


Specifies the depth of the screen. 


Defined only for DirectColor and TrueColor. Each mask has one 
contiguous set of bits with no intersections. 


Defined only for DirectColor and TrueColor. Each mask has one 
contiguous set of bits with no intersections. 


Specifies the screen. 
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visual Specifies the visual. 


visualid Specifies the visual ID. 


Related Information 
The XGetVisuallinfo subroutine, XMatchVisuallnfo subroutine, XVisuallDFromVisual 
subroutine 





XSetWindowAttributes Data Structure 


#define CWBackPixmap (1L<<0) 
#define CWBackPixel (1L<<1) 
#define CWBorderPixmap (1L<<2) 
#define CWBorderPixel (1L<<3) 
#define CWBitGravity (1L<<4) 
#define CWWinGravity (1L<<5) 
#define CWBackingStore (1L<<6) 
#define CWBackingPlanes (1L<<7) 
#define CWBackingPixel (1L<<8) 
#define CWOverrideRedirect (1L<<9) 
#define CWSaveUnder (1L<<10) 
#define CWEventMask (1L<<11) 
#define CWDontPropagate (1L<<12) 
#define CWColormap (1L<<13) 
#define CWCursor (1L<<14) 


typedef struct { 
Pixmap background_pixmap; 
unsigned long background_pixel; 
Pixmap border _pixmap; 
unsigned long border pixel; 
int bit_gravity; 
int window_gravity; 
int backing_store; 
unsigned long backing_planes; 
unsigned long backing pixel; 
Bool save_under; 
long event_mask; 
long do_not_propagate_mask; 
Bool override redirect; 
Colormap colormap; 
Cursor cursor; 

} XSetWindowAttributes; 


The following table lists the defaults for each window field and indicates if the field is 
applicable to InputOutput or InputOnly windows. 
Window Field 


Default Values InputOutput InputOnly 
background_pixmap 


Nowe CT Yes | NO 
background_pixel Undefined | Yes | No 
bdo ia CopyFionParent | Yes | No] 
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border_pixel 
bit_gravity 


win_gravity 
backing_store 
backing_planes 
backing_pixel 


save_under 
event_mask 
do_not_propagate_mask 
override_redirect 
colormap 





cursor 


The fields of the XSetWindowaAttributes data structure are as follows: 


background_pixmap Specifies the pixmap to be used for a window background. 
This pixmap can be any size, but some sizes are faster than 
others. Use the XQueryBest Sizes subroutine to determine 
the optimum size. The background_pixmap field can be set to 
a pixmap ID, or either the value of None or ParentRelative. 
The default is the value of None. The background_pixmap 
field and the window must have the same depth, ora 
BadMatch error is returned. 


Only InputOutput windows can have backgrounds. 


When regions of the window are exposed and the X Server 
has not retained the contents of the window, the X Server 
automatically tiles the regions with the window background as 
long as the background_pixmap field is not the value of None. 


e Ifthe background_pixmap field is set to the value of None, 
the contents of the previous screen are left in place if the 
window and the parent window have the same depth. 
Otherwise, the initial contents of the exposed regions are 
undefined. Expose events are then generated for the 
regions, even if the background_ pixmap field is the value of 
None. 


e lf the background_pixmap field is set to ParentRelative, the 
following occurs: 


— The background_pixmap field of the parent window is 
used if the child window has the same depth as the 
parent window, or a BadMatch error is returned. 


— The window has no defined background. If the parent 
window has a background_pixmap field of the value of 
None, the window also has a background_pixmap field of 
the value of None. | 


— Acopy of the background_pixmap field of the parent 
window is not made. The background_pixmap field of the 
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background_pixel 


border_pixmap 


border_pixel 


parent window is examined each time the 
background_pixmap field of the child window is required. 


— The background tile origin always aligns with the 
background tile origin of the parent window. Otherwise, 
the background tile origin is always the child window 
origin. 


Setting a new background with the background_pixmap field 
overrides any previous background_pixmap field. The 
background_pixmap field can be freed immediately if no 
further explicit reference is made to it. The X Server keeps a 
copy to use when needed. 


Specifies a pixel value of a single color for the background of 
the window. This field can be set to any pixel value. The 
default value for the background _pixel field is undefined. 


If the background_pixel tield is specified, it overrides the 
default background_pixmap field or any value set in the 
background_pixmap field, and a pixmap of undefined size is 
created and filled with the specified pixel and used for the 
background. All pixels, in the background of the window, will 
be set to this value. Range checking is not performed on the 
pixel, as it is truncated to the appropriate number of bits. 


Setting a new background with the background_pixel field 
overrides any previous background. 


Specifies the pixmap for the border of a window. This pixmap 
can be any size. The border_pixmap field and the child 
window must have the same depth, or a BadMatch error is 
returned. 


Only InputOutput windows can have a border. 


Setting a new border with the border_pixmap field overrides 
any previous border. Setting a border_pixmap field value 
overrides the default value. The default value is 
CopyFromParent. 


If the border_pixmap is CopyFromParent, the border_pixmap 
field is copied from the parent window. Subsequent changes to 
the border attribute of the parent window do not affect the child 
window. 


The pixmap used for the border_pixmap field can be freed 
immediately if no further explicit reference to it is made. If the 
pixmap used for the border_pixmap field is freed, the X Server 
may or may not keep a copy of it. The X Server can use the 
same pixmap each time the window is repainted or it may 
make a copy. 


Specifies a pixel value to be used for the window border. The 
server creates a pixmap of unspecified size filled with the pixel 
for the window border. The border tile origin is always the 
same as the background tile origin. The default for the 
border_pixel field is undefined. Range checking is not 
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performed on the pixel, as it is truncated to the appropriate 
number of bits. 


Only InputOutput windows can have a border. 


If you specify a border_pixel field, it overrides the default value 
or the assigned value of border_pixmap field. Then, all pixels 
in the border of the window are set to the border_pixel field 
value. 


The output to a window is always clipped to the inside of the 
window so that graphics operations are not affected by the 
border. 


bit_gravity Specifies which region of the window should be retained when 
an InputOutput window is resized. The default bit_gravity is 
the ForgetGravity value. Changing the inside width or height 
of the window causes the contents of the window to be moved 
or lost depending on the bit_gravity field of the window. The 
values for the bit_gravity field include: 


ForgetGravity Indicates that the contents of the window 
are always discarded after a size change, 
even if a backing store or save under has 
been requested. The window is tiled with its 
background, and one or more Expose 
events are generated. If no background is 
defined, the existing screen contents are 
not altered. Some X Servers may ignore 
the specified bit_gravity field and always 
generate exposure events. 


StaticGravity Indicates that the contents or origin of the 
window should not move relative to the 
origin of the root window. If the change in 
size of the window is coupled with a change 
in position (x, y), the change in position of 
each pixel becomes (-x, -y). 


The StaticGravity value takes effect only 
when the width or height of the window is 
changed, not when iné window Is moved. 


If the inside width or height of a window is not changed and if 
the window is moved or its border is changed, the contents of 
the window are not lost but are moved with the window. Fora 
change of width and height, the (x, y) pairs are defined as 


follows: 

Gravity Coordinates Direction 
NorthWestGravity (0, 0) 
NorthGravity (Width/2, 0) 
NorthEastGravity (Width, 0) 
WestGravity (0, Height/2) 
CenterGravity (Width/2, Height/2) 
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win_gravity 


EastGravity (Width, Height/2) 


SouthWestGravity (0, Height) 
SouthGravity (Width/2, Height) 
SouthEastGravity (Width, Height) 


When a window with one of these bit_gravity field values is 
resized, the corresponding pair defines the change in position 
of each pixel in the window. 


Specifies how the InputOutput or InputOnly window should 
be repositioned if the parent window is resized. Changing the 
inside width or height of the window causes child windows to 
be reconfigured, depending on the specified win_gravity field. 
The default for the win_gravity field is the value of 
NorthWestGravity. 


If the inside width or height of a window is not changed and if 
the window is moved or its border is changed, the contents of 
the window are not lost but are moved with the window. For a 
change of width and height, the (x, y) pairs are defined as 
follows: 


Gravity Coordinates Direction 
NorthWestGravity (0, 0) 
NorthGravity (Width/2, 0) 
NorthEastGravity (Width, 0) 
WestGravity (0, Height/2) 
CenterGravity (Width/2, Height/2) 
EastGravity (Width, Height/2) 
SouthWestGravity (0, Height) 
SouthGravity (Width/2, Height) 
SouthEastGravity (Width, Height) 


When a window with one of these win_gravity field values has 
its parent window resized, the corresponding pair defines the 
change in position of the window within the parent window. 
When the window is repositioned, a GravityNotify event is 
generated. 


StaticGravity If the change in size of the window is 
coupled with a change in position (x, y), 
the change in position of a child window 
when the parent window is resized 
becomes (-x, -y). 


The StaticGravity value takes effect 
only when the width or height of the 
window is changed, not when the 
window is moved. 
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UnmapGravity This is like the NorthWestGravity value; 
the window is not moved, but the child 
window is unmapped when the parent 
window is resized, and an UnmapNotify 
event is generated. 


backing_store Advises the X Server what to do with the contents of a 
window. Some implementations may choose to maintain the 
contents of InputOutput windows. If the X Server maintains 
the contents of a window, the pixels saved offscreen are 
known as the backing store. This field can be set to the 
following values: 


NotUseful Advises the X Server that maintaining 
contents is not necessary. Some X 
implementations can still maintain 
contents; therefore, exposure events are 
not generated. This is the default value. 


WhenMapped Advises the X Server that maintaining 
contents of obscured regions when the 
window is mapped would be beneficial. 
The X Server can generate an Expose 
event when the window is created. 


Always Advises the X Server that maintaining 
contents even when the window is 
unmapped would be beneficial. Even if 
the window is larger than the parent 
window, this requests that the X Server 
maintain the complete contents of the 
window, not just the contents of the 
region within the boundaries of the 
parent window. While the X Server 
maintains the contents of the window, 
Expose events are not normally 
generated. The X Server can stop 
maintaining contents at any time. 


When the contents of obscured regions of a window are beina 
Maintained, the regions obscured by noninferior windows are 
included in the destination of graphics requests (and source, 
when the window is the source). Regions obscured by inferior 


windows, however, are not included. 


backing_planes Indicates (with one bits) which bit planes of the InputOutput 
window hold dynamic data that must be preserved in the 
backing store and during save unders. If you request backing 
store or save unders, the backing_planes field will minimize 
the amount of off-screen memory required to store your 
window. The default is all bits set to the value of 1. 


backing_pixel Specifies the values to use in planes not covered by the 
backing_planes field. The X Server is free to save only the 
specified bit planes in the backing store or the save under and 
is free to regenerate the remaining planes with the specified 
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save_under 


event_mask 


do_not_propagate_mask 


override_redirect 


colormap 


pixel value. Any extraneous bits in these values, beyond the 
depth of the window, can be ignored. If you request backing 
store or save unders, the backing_pixel field will minimize the 
amount of off-screen memory required to store your window. 
The default is the value of 0. 


If the save_under field is the value of True, the X Server is 
advised that saving the contents of the windows that it 
obscures would be beneficial when this window is mapped. 
The default is the value of False. 


Some server implementations can preserve bits of 
InputOutput windows under other InputOutput windows. 
This is not the same as preserving the contents of a window. If 
transient windows, such as pop-up menus, request that the 
system preserve the bits under them, the temporarily obscured 
applications do not have to repaint. 


Defines events the client is interested in for this InputOutput 
or InputOnly window or, in some cases, for the inferiors of the 
window. This mask is the bitwise-inclusive OR of one or more 
of the valid event mask bits. If the NoEventMask constant is 
specified, no maskable events are reported. The default is the 
empty set. 


Defines events that should not be propagated to ancestor 
windows when no client has the event type selected in this 
window. These masks are the bitwise-inclusive OR of one or 
more of the valid event mask bits. If the NoEventMask 
constant is specified, no maskable events are reported. The 
default is the empty set. 


Specifies if a map or configure request on a window should 
override a SubstructureRedirectMask request on the parent 
window. The default is the value of False. 


To control window placement or to add decoration, a window 
manager may need to intercept or redirect a map or configure 
request. Pop-up windows, however, need to be mapped so 
that a window manager does not interfere with the response 
they receive. To do this, the override_redirect field must be 
used. 


Specifies the colormap, if any, that best reflects the true colors 
of an InputOutput window. The colormap must have the same 
visual type as the window, or a BadMatch error is returned. 
The colormap field can be set to a specific colormap or to the 
value of CopyFromParent, which is the default. 


If the colormap field is set to the value of CopyFromParent, 
the colormap of the parent window is copied and used by the 
child window. However, the child window must have the same 
visual type as the parent, or a BadMatch error is returned. A 
BadMatch error is also returned if the parent window has the 
colormap field is set to the value of None. The colormap is 
copied by sharing the colormap object between the child and 
parent windows, not by making a complete copy of the 


Chapter 5. Enhanced X-Windows 5-69 


cursor 


colormap contents. Subsequent changes to the parent window 
do not affect the child window. 


If a cursor is specified, it is used whenever the pointer is in the 
specified window. The default is the value of None. 


If the value of None is specified, the cursor of the parent is 
used when the pointer is in the InputOutput or InputOnly 
window. Any change in the parent cursor will change the 
displayed cursor immediately. Use the XFreeCursor 
subroutine to free the cursor immediately if no further explicit 
reference to it is made. 


XWindowChanges Data Structure 


#define 
#define 
#define 
#define 
#define 
#define 
#define 


CWX (1<<0) 
CWY (1<<1) 
CWWidth (1<<2) 
CWHeight (1<<3) 
CWBorderWidth (1<<4) 
CWSibling (1<<5) 
CWStackMode (1<<6) 


typedef struct { 


Ine. yp Vs 


int width, height; 
int border_width; 
Window sibling; 
int stack_mode; 

} XWindowChanges 


The fields of the XWindowChanges data structure are as follows: 


x 


width 


height 


border_width 


sibling — 


Specifies the position of the x coordinate of the upper-left outer corner of 
the window. This coordinate is relative to the origin of the parent window. 


Specifies the position of the y coordinate of the upper-left outer corner of 
the window. This coordinate is relative to the origin of the parent window. 


Specifies ihe wiaih of ihe inside of the window, excluding the border. This 
field should be a nonzero value or a BadValue error is returned. Attempts 
to configure a root window have no effect. 


Specifies the width of the inside of the window, excluding the border. This 
field should be a nonzero value or a BadValue error is returned. Attempts 
to configure a root window have no effect. 


Specifies the width of the border in pixels. Changing only the 
border_width field leaves the outer-left corner of the window in a fixed 
position, but moves the absolute position of the window origin. Attempts 
to change the border_width field on an InputOnly window will result in a 
BadMatch error. | 


Specifies the sibling window for stacking operations. If the sibling field is 
specified without the stack_mode field, a BadMatch error will result. 
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stack_mode- Specifies how the window is to be restacked. The stack_mode field can 
j be the Above, Below, Toplf, Bottomif, or Opposite value. 


If a sibling and a stack_mode field are specified, the window is restacked 


as follows: 
StackMode 


Above 


Below 


Toplf 


Bottomlif 


Opposite 


Sibling Specified. 


The window is placed just above the sibling 
window. 


The window is placed just below the sibling 
window. 


lf the sibling window occludes the window, the 
window is placed at the top of the stack. 


If the window occludes the sibling window, the 
window is placed at the bottom of the stack. 


If the sibling window occludes the window, the 
window is placed at the top of the stack. 
Otherwise, if the window occludes the sibling 
window, the window is placed at the bottom of 
the stack. 


If the stack_mode field is specified without a sibling window, the window 


is restacked as follows: 


StackMode 
Above 
Below 


Toplf 


Bottomif 


Opposite 


Sibling Not Specified. 
The window is placed at the top of the stack. 
The window is placed at the bottom of the stack. 


If any sibling window occludes the window, the 
window is placed at the top of the stack. 


If the window occludes any sibling window, the 
window is placed at the bottom of the stack. 


If any sibling window occludes the window, the 
window is placed at the top of the stack. 
Otherwise, if the window occludes any sibling 
window, the window is placed at the bottom of 
the stack. 


If the override_redirect field of the window is the value of False, and if some other client has 
selected the SubstructureRedirectMask on the parent window, then the X Server 
generates a ConfigureRequest event, and no further processing is performed. 


Otherwise, if some other client has selected the ResizeRedirectMask value on the window 
and the inside width or height of the window is being changed, a ResizeRequest event is 
- generated, and the current inside width and height are used instead. 


The override_redirect field of the window does not affect the ResizeRedirectMask value, 
and the SubstructureRedirectMask value on the parent window has precedence over the 
ResizeRedirectMask value on the window. 
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When the geometry of the window is changed as specified, the window is restacked among 
sibling windows, and a ConfigureNotify event is generated if the state of the window | 
actually changes. The X Server generates GravityNotify events after generating — 
ConfigureNotify events. If the inside width or height of the window has changed, the 
children of the window are affected as follows: 


e If the size of the window actually changes, the subwindow may move according to the 
window gravity. Depending on the window’s bit gravity, the contents of the window may 
also be moved. 


e If regions of the window were obscured but are not now, exposure processing is 
performed on formerly obscured windows, including the window itself and its interiors. 


e By increasing the width or height, exposure processing is also performed on any new 
regions of the window and on any regions where window contents are lost. 


e The restack check, specifically the computation for the Bottomlf, Toplf, and Opposite 
values, is performed with respect to the final size and position of the window as controlled 
by the other fields of the request, not the initial position of the window. A sibling field 
should be specified with a stack_mode field. 


Related Information 
The XChangeWindowAittributes subroutine, XCirculateSubwindows subroutine, 
XCirculateSubwindowsDown subroutine, XCirculateSubwindowsUp subroutine, 
XConfigureWindow subroutine, XLowerWindow subroutine, XMoveResizeWindow 
subroutine, XMoveWindow subroutine, XRaiseWindow subroutine, XResizeWindow 
subroutine, XRestackWindows subroutine, XSetWindowBackground subroutine, 
XSetWindowBackgroundPixmap subroutine, XSetWindowBorder subroutine, 
XSetWindowBorderPixmap subroutine, XSetWindowBorderWidth subroutine, 
XTranslateCoordinates subroutine. 


The ChangeWindowAttributes protocol request, CirculateWindow protocol request, 
ConfigureWindow protocol request. 
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XWindowsAttributes Data Structure 


typedef struct { 
int x, y; 
int width, height; 
int border_width; 
int depth; 
Visual *visual; 
Window root; 
int class; 
int bit_gravity 
int window_gravity; 
int backing_store; 


/* location of window */ 

/* width and height of window */ 

/* border width of window */ 

/* depth of window */ 

/* the associated visual structure */ 
/* root of screen containing window */ 
/* InputOutput, InputOnly */ 

/* one of the bit gravity values */ 

/* one of the window gravity values */ 
/* NotUseful, WhenMapped, Always */ 


unsigned long backing _planes;/* planes to be preserved if 


possible */ 


unsigned long backing_pixel; /* value to be used when restoring 


Bool save_under; 
Colormap colormap; 
Bool map_installed 


int map_state; 


planes */ 
/* boolean, should bits under be 
saved? */ 
/* colormap to be associated with 
window */ 


: /* boolean, is colormap currently 


installed? */ 
/* IsUnmapped, IsUnviewable, 
IsViewable */ 


long all_event_masks; /* set of events all people have 


interest in */ 


long your_event_mask; /* my event mask*/ 
long do_not_propagate_mask; /* set of events that should not 


propagate */ 


Bool override redirect; /* boolean value for 


Screen *screen; 
} XWindowAttributes; 


override-redirect */ 
/* back pointer to correct screen */ 


The fields of the XWindowAttributes data structure are as follows: 


x 


wiath 


height 


border_width 


Defines the x coordinate of the drawable. If the drawable is a 
window, this coordinate specifies the upper-left outer-corner of 
the window relative to the origin of the parent window. If the 
drawable is a pixmap, this coordinate is set to a value of 0. 


Defines the x coordinate of the drawable. If the drawable is a 
window, this coordinate specifies the upper-left outer-corner of 
the window relative to the origin of the parent window. If the 
drawable is a pixmap, this coordinate is set to the value of 0. 


Specifies the width of the inside of the window, excluding the 
border, for a window. 


Specifies the height of the inside of the window, excluding the 
border, for a window. 


Specifies the width of the border in pixels. If the drawable is a 
pixmap, this field is set to the value of 0. 
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depth 


visual 


root 


class 


bit_gravity 


win_gravity 


backing_store 
backing_planes 


backing_pixel 


save_under 


colormap 


map_installed 


Specifies the depth of the pixmap or window in bits per pixel 
for the object. The depth must be supported by the root 
window of the specified drawable. 


Specifies a pointer to the Visual structure associated with the 
screen. 


Specifies the root ID of the screen containing the window. 


Specifies the window class, which is either the InputOutput or 
InputOnly value. 


Specifies the bit gravity of the window. The bit_gravity field can 
be set to one of the following values: 


_ CenterGravity SouthGravity 
EastGravity SouthEastGravity 
ForgetGravity SouthWestGravity 
NorthGravity StaticGravity 
NorthEastGravity WestGravity 
NorthWestGravity 


Specifies the gravity of the window. The win_gravity field can 
be set to one of the following values: 


CenterGravity SouthGravity 
EastGravity SouthEastGravity 
ForgetGravity SouthWestGravity 
NorthGravity StaticGravity 
NorthEastGravity WestGravity 
NorthWestGravity 


Indicates how the X Server should maintain the contents of a 
window. It can be set to the NotUseful, WhenMapped, or 
Always value. 


Indicates which bit planes of the window that hold dynamic 
data musi De preserved in backing_store and during 
Save_under. 


Indicates the values to use when restoring planes from a 
partial backing store. 


Indicates if the area under the newly mapped windows should 


be saved and restored. It can be either the value of True or 
False. 


Indicates colormap for the window specified. It can be set to a 
colormap ID or to the value of None. 


Indicates if the colormap is currently installed. It can be either 
the value of True or False. 
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map_state Indicates the state of the window. It can be lsUnmapped, 
IsUnviewable, or IsViewable value. If the window is mapped, 
but an ancestor is unmapped, the map_state field is set to the 
value of IsUnviewable. 


all_event_masks Specifies the bitwise inclusive-OR of all event masks selected 
on the window by interested clients. 


your_event_mask Specifies the bitwise inclusive-OR of all event masks selected 
by the querying client. 


do_not_propagate_mask Specifies the bitwise inclusive-OR gate or operation of the set 
of events that should not propagate. 


override_redirect Indicates if this window overrides structure control facilities. It 
can be either the value of True or False. If the 
override_redirect field is the value of True, window manager 
clients usually should ignore the window. 


Transient windows should mark the windows associated with 
them. 


screen Returns a pointer to the correct screen. 


Related Information 
The XGetGeometry subroutine, XGetWindowAtiributes subroutine, XQueryPointer 
subroutine, XQueryTree subroutine. 


XColor Data Structure 


typedef struct { 


unsigned long pixel; /* pixel value */ 
unsigned short red, green, blue; /* RGB values */ 
char flags; /* DoRed, DoGreen, DoBlue */ 
char pad; 
} XColor; 


The fields of the XColor data structure are as follows: 


blue Specifies a scale between 0 and 65535. That is, on full, the color value would be 
65535 independent of the number of bit planes of the display. For half brightness 
in a color, the value would be 32767. The color value would be 0 for off. This 
value gives uniform results for color values across displays with different numbers 
of bit planes. 


flags Specifies which colors are to be set. The flags field can be one or more of the 
DoRed, DoGreen, or DoBlue values. 


green Specifies a scale between 0 and 65535. That is, on full, the color value would be 
65535 independent of the number of bit planes of the display. For half brightness 
in a color, the value would be 32767. The color value would be 0 for off. This 
value gives uniform results for color values across displays with different numbers 
of bit planes. 
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pad Indicates to fill unused positions in a field with dummy data, usually zeros or 


blanks. 
pixel Specifies the value of the pixel. 
red Specifies a scale between 0 and 65535. That is, on full, the color value would be 


65535 independent of the number of bit planes of the display. For half brightness 

in a color, the value would be 32767. The color value would be 0 for off. This 

value gives uniform results for color values across displays with different numbers 
_ Of bit planes. 


Related Information 
The XCopyColormapAndFree subroutine, XCreateColormap subroutine, XFreeColormap 
subroutine, XSetWindowColormap subroutine. 


The ChangeWindowAitributes protocol request, CopyColormapAndFree, 


CreateColormap protocol request, FreeColormap protocol request. 





XGCValues Data Structure 


#define GCFunction (1L<<0) 
#define GCPlaneMask (1L<<1) 
#define GCForeground (1L<<2) 
#define GCBackground (1L<<3) 
#define GCLineWidth (1L<<4) 
#define GCLineStyle (1L<<5) 
#define GCCapStyle (1L<<6) 
#define GCJoinStyle (1L<<7) 
#define GCFillStyle (1L<<8) 
#define GCFillRule (1L<<9) 
#define GCTile (1L<<10) 
#define GCStipple (1L<<11) 
#define GCTileStipxXOrigin (1L<<12) 
#define GCTileStipYOrigin (1L<<13) 
#define GCFont (1L<<14) 
#define GCSubwindowMode (1L<<15) 
#define GCGraphicsExposures (1L<<16) 
#define GCClipxXOrigin (1L<<17) 
#define GCClipYOrigin (1L<<18) 
#define GCClipMask (1L<<19) 
#define GCDashOffset (1L<<20) 
#define GCDashList (1L<<21) 
#define GCArcMode (1L<<22) 


typedef struct { 
int function; /* logical operation */ 
unsigned long plane _mask; /* plane mask */ 
Unsigned long foreground; /* foreground pixel */ 
unsigned long background; /* background pixel */ 
int line width; /* line width (in pixels) */ 
int line style; /* LineSolid, LineOnOffDash, 
LineDoubleDash */ 
/* CapNotLast, CapButt, CapRound, 
CapProjecting */ 


int cap_style; 
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int join_style; /* JoinMiter, JoinRound, 
JoinBevel */ 

int fill style; /* FillSolid, FillTiled, 
FillStippled, or 
FillOpaqueStippled */ 


int fill rule; /* EvenOddRule, WindingRule */ 

int arc mode; /* ArcChord, ArcPieSlice */ 

Pixmap tile; /* tile pixmap for tiling 
operations */ 

Pixmap stipple; /* stipple 1 plane pixmap for 
stippling */ 

int ts_x_origin; /* x offset for tile or stipple 

a operations */ 

int ts_y origin; /* y offset for tile or stipple 
operations */ 

Font font; /* default text font for text 
operations */ 

int subwindow_mode; /* ClipByChildren, 


IncludeInferiors */ 
Bool graphics exposures; /* Boolean, should exposures be 
generated */ 


int clip x origin; /* x origin for clipping */ 

int ¢lip vy origin; /* y origin for clipping */ 

Pixmap clip mask; /* bitmap clipping; other calls 
for rects */ 

int dash_ offset; /* patterned or dashed line 


information */ 
char dashes; 
} XGCValues; 


In graphics operations, given a source and destination pixel, the result is computed bitwise 
on corresponding bits of the pixels. A Boolean operation is performed in each bit plane. 


For a line with coincident endpoints (x1=x2, y1=y2), when the cap_style field is applied to 
both endpoints, the semantics depends on the /ine_width field and the cap_style field: 


CapNotLast Nothing is drawn. 
CapButt A single pixel is drawn. 


CapButt wide | Nothing is drawn. 


CapRound wide | The closed path is a circle, centered at the endpoint, 
with diameter equal to the /ine_widfth field. 
CapRound A single pixel is drawn. 


CapProjecting The closed path is a square 4, aligned with the coor- 
dinate axes, centered at the endpoint, with sides 
equal to the /ine_width field. 


CapProjecting A single pixel is drawn. 


For a line with concident endpoints (x1=x2, y1=y2), when the join_style field is applied at 

one or both endpoints, the effect is as if the line was removed from the overall path. 

However, if the total path consists of or is reduced to a single point joined with itself, the 
effect is the same as when the cap_style field is applied at both endpoints. 
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The fields of the XGCValues data structure are as follows: 
function Specifies the logical operation to be performed. 


plane_mask Specifies the operations to a subset of planes that need to be 
restricted. The result is computed by the following: 


((srce FUNC dst) AND plane-mask) OR (dst AND (NOT plane-mask) ) 


Range checking is not performed on the values for the foreground, 
background, or plane_mask fields. These values are truncated to 
the appropriate number of bits. 


line_width Specifies the width of the line, measured in pixels. It can be 


greater than or equal to 1 (wide line) or can be the special value 0 
(thin line). 


Wide lines are drawn centered on the path described by the 
graphics request. 


Unless otherwise specified by the join_style or the cap_style fields, 
the bounding box of a wide line with endpoints [x1, y1] to [x2, y2] 
and width wis a rectangle with vertices at the following real 
coordinates: 


[xl—(w*sn/2), yl+(w*cs/2)], [xl+(w*sn/2), y1l—(w*es/2) J 


[x1—(w*sn/2), ylt+(w*cs/2)], [x1+(w*sn/2), yl—(w*cs/2) } 


In this example, sn is the sine of the angle of the line, and cs is 
the cosine of the angle of the line. A pixel is part of the line and is 
drawn that way only if the center of the pixel is fully inside the 
bounding box, which has infinitely thin edges. If the center of the 
pixel is exactly on the bounding box, it is part of the line only if the 
interior is immediately to its right (the x increasing direction). Pixels 
with centers on a horizontal edge are a special case and are part 
of the line only if the interior or the boundary is immediately below 
(the y increasing direction) and the interior or the boundary is 
immediately to the right (the x increasing direction). 


Thin lines (zero line width) are one pixel wide lines drawn using an 
unspecified, device-dependent algorithm. There are only the 
follGwing two consiraints on this algorithm: 


e {fa line is drawn unclipped from [x1, yl] to [x2, y2] and if 
another line is drawn unclipped from [xl+dx, yl+dy] to 
[x2+dx, y2+dy], apoint [x, y] is touched by drawing the 
first line only if the point [x+dx, y+dy] is touched by drawing 
the second line. 


e The effective set of points comprising a line cannot be affected 
by clipping. That is, a point is touched in a clipped line only if 
the point lies inside the clipping region and the point would be 
touched by the line when drawn unclipped. 


A wide line drawn from [x1,. y1] to [x2, y2] always draws the 
same pixels as a wide line drawn from {x2, y2]to[x1, yl], 
not counting the cap_style and the join_style fields. A line_width 
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line_style 


cap_style 


join_style 


field of O may differ from a /ine_width field of 1 in which pixels are 
drawn. 


In general, drawing a thin line is faster than drawing a wide line of 
width 1. However, because of their different drawing algorithms, 
thin lines may not mix well, aesthetically speaking, with wide lines. 
If it is desirable to obtain precise and uniform results across all 
displays, a client should always use a /ine_width of 1, rather than a 
line_width of 0. 


Defines which sections of a line are drawn. The /ine_style field can 
be one of the following values: 


LineSolid The full path of the line is drawn. 


LineDoubleDash The full path of the line is drawn, but the 
even dashes are filled differently than the 
odd dashes (see fill-style) with the CapButt 
value used where even and odd dashes 
meet. 


LineQnOffDash Only the even dashes are drawn, and the 
cap_style field applies to all internal ends of 
the individual dashes, except the 
CapNotLast value is treated as the 
CapBuit value. 


Defines how the endpoints of a path are drawn. The cap_style field 
can be one of the following values: 


CapNotLast Equivalent to the CapButt value, except 
that for a fine_wiath field of 0 or 1, the final 
endpoint is not drawn. 


CapButt Square at the endpoint, perpendicular to 
the slope of the line, with no projection 
beyond. 

CapRound A circular arc with the diameter equal to the 


line_width field, centered on the endpoint 
(equivalent to the CapButt value for a 
line_width field 0 or 1). 


CapProjecting Square at the end, but the path continues 
beyond the endpoint for a distance equal to 
half the /ine_width field (equivalent to the 
CapButt value for Jine_width field 0 or 1). 


Defines how corners are drawn for wide lines. The join_style field 
can be one of the following values: 


JoinMiter The outer edges of two lines extend to 
meet at an angle. 


JoinRound A circular arc with diameter equal to the 
line_width field, centered on the join point. 
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JoinBevel CapButt endpoint styles, and then the 
triangular notch filled. 


tile Specifies the tile to be used. The tile pixmap must have the same 
root window and depth as the graphics context, or a BadMatch 
error results.. The tile field is interpreted relative to the origin of 
whatever destination drawable is specified in a graphics request. 


stipple Specifies the stipple to be used. The stipple pixmap must have 
depth one and must have the same root window as the GC, ora 
BadMatch error results. For stipple operations where the fi/l_style 
field is FillStippled, but not FillOpaqueStippled, the stipple 
pattern is tiled in a single plane and acts as an additional clip mask 
to be ANDed with the clip_mask field. Any size pixmap can be 
used for tiling or stippling although some sizes may be faster to 
use than others.The stipple field is interpreted relative to the origin 
of whatever destination drawable is specified in a graphics 
request. 


clip_x_origin Specifies that the field is interpreted relative to the origin of 
whatever destination drawable is specified in a graphics request. 


clip_y_origin Specifies that the field is interpreted relative to the origin of 
whatever destination drawable is specified in a graphics request. 


fill_style Specifies that the field defines the contents of the source for line, 
‘text, and fill requests. For all text and fill requests, for line requests 
with /line_style field of LineSolid, and for the even dashes for line 
requests with line_style field of LineOnOffDash or 
LineDoubleDash the following applies: 


FillSolid Foreground. 
FillTiled Tile. 


FillOpaqueStippled A tile with the same width and height as 
stipple, but with stipple background has 
a 0 and with stipple foreground has a 1. 


FillStippled Foreground masked by stipple. 
Wren drawing iines with the line_style field value of 
LineDoubleDash, the odd dashes are controlled by the fi/l_style 
field in the following manner: 
FillSolid Background. 
FillTiled Same as even dashes. 
FillOpaqueStippled Same as even dashes. 
FillStippled Background masked by stipple. 


Storing a pixmap in a GC may result in a copy being made. If the 

pixmap is later used as the destination for a graphics request, the 
change may be reflected in the graphics context. If the pixmap is 

used simultaneously in a graphics request both as a destination 
_and as a tile or stipple, the results are not defined. 
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Se 


dashes 


dash_offset 


clip_mask 


subwindow_mode 


Specifies the dash list for the dashed line style to be set for the 
specified GC. 


The value allowed by the dashes field is a simplified form of the 
more general patterns that can be set with the XSetDashes 
subroutine. Specifying a value of N is equivalent to specifying the 
two-element list [N, N] in the XSetDashes subroutine. N 
specifies the length of the dash list. This value must be nonzero, or 
a BadValue error results. The default dash list in a newly created 
GC is equivalent to [4,4]. 


Specifies the phase of the pattern for the dashed line style to be 
set for the graphics context specifying how many elements into the 
dash list the pattern should actually begin in any single graphics 
request. 


Dashing is continuous through path elements combined with 
join_style, but is reset to the dash_offset each time a cap_style is 
applied at a line endpoint. 


The unit of measure for dashes is the same as in the ordinary 
coordinate system. Ideally, a dash length is measured along the 
slope of the line, but implementations are required to match only 
for horizointa!l and vertical lines. It is suggested that you measure 
the length along the major axis of the line. The major axis is 
defined as the x axis for lines drawn at an angle of between -45 
and +45 degrees or between 315 and 225 degrees from the x axis. 
For all other lines, the major axis is the y axis. The default value 
for the dash list in a newly created GC is equivalent to [4, 4]. 


Restricts writes to the destination drawable. If a pixmap is 
specified as the clip_mask field, it must have a depth of one and 
have the same root window as the GC. If the clip_mask field is the 
value of None, the pixels are always drawn, regardless of the clip 
origin. The clip_mask field can also be set with the 
XSetClipRectangles or XSetRegion subroutines. Only pixels 
where the clip_mask field has a 1-bit are drawn. Pixels are not 
drawn outside the area covered by the clip_mask field or where 
the clip_mask field has a 0 bit. It affects all graphics requests. The 
clip_mask field does not clip sources. The clip_mask field origin is 
interpreted relative to the origin of the specified destination 
drawable in the graphics request. 


Specifies how the subwindow should be clipped. The 
subwindow_mode field can be one of the following values: 


ClipByChildren Indicates that both source and 
destination windows are clipped 
additionally by all viewable InputOutput 
children. 


Includeinferiors Indicates that neither the source window 
nor the destination window is clipped by 
inferiors. This results in drawing through 
the boundaries of subwindows. Using 
the Inciudeinferiors value on a window 
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with the depth of one with mapped 
inferiors of differing depth is allowed, but 
the semantics are undefined by the core 
protocol. 


fill_rule Defines which pixels are inside (drawn) for paths given in the 
XFillPolygon subroutine. The fill_rule field can be set to one of 
the following values: 


EvenOddRule Specifies that a point is inside if an 
infinite ray with the point as origin 
crosses the path an odd number of 
times. 


WindingRule Specifies that a point is inside if an 
infinite ray with the point as origin 
crosses an unequal number of clockwise 
and counterclockwise directed path 
segments.A clockwise directed path 
segment is one that crosses the ray from 
left to right as observed from the point.A 
counterclockwise segment is one that 
crosses the ray from right to left as 
observed from the point. 


For EvenOddRule and WindingRule, a point is infinitely small, 
and the path is an infinitely thin line. 


arc_mode Controls filling in the XFillArcs subroutine. The arc_mode field 
can be one of the following values: 
ArcPieSlice Specifies that arcs are pie-sliced filled. 
ArcChord Specifies that arcs are chord-filled. 
graphics_exposures Controls the GraphicsExpose event generation for the 


XCopyArea and XCopyPlane subroutines and any similar 
requests defined by extension subroutines. The GraphicsExpose 

_ events are sent even when they are not explicitly requested. To 
suppress them, set the graphics_exposures field to the value of 
Faise. 


Related Information. 
The AllPlanes macro. 


The XChangeGC subroutine, XCopyGC subroutine, XCreateGC subroutine, XFreeGC 
subroutine, XQueryBestSize subroutine, XQueryBestStipple subroutine, XQueryBestTile 
subroutine, XSetArcMode subroutine, XSetBackground subroutine, XSetClipMask 
subroutine, XSetClipOrigin subroutine, XSetClipRectangles subroutine, XSetDashes 
subroutine, XSetFillRule subroutine, XSetFillStyle subroutine, XSetFont subroutine, 
XSetForeground subroutine, XSetFunction subroutine, XSetGraphicsExposures 
subroutine, XSetLineAttributes subroutine, XSetPlaneMask subroutine, XSetState 
subroutine, XSetStipple subroutine, XSetSubwindowMode subroutine, XSetTile 
Subroutine, XSetTSOrigin subroutine 
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XStandardColormap Data Structure 


typedef struct { 
Colormap colormap; 
unsigned long red_max; 
unsigned long red mult; 
unsigned long green max; 
unsigned long green mult; 
unsigned long blue_max; 
unsigned long blue _ mult; 
unsigned long base_pixel; 

} XStandardColormap; 


The properties containing the XStandardColormap data structure have the type 
RGB_COLOR_MAP. 


The fields in the XStandardColormap data structure include the following: 


colormap 


red_max 
green_max 


blue_max 


red_mult 
green_mult 


blue_mult 


base_pixel 


Specifies the 1D of a colormap created by the XCreateColormap 
subroutine. 


Specifies the maximum red values. 
Specifies the maximum green values. 


Specifies the maximum blue values. Each color coefficient ranges from zero 
(0) to its maximum, inclusive. 


An example of a common colormap allocation is 3/3/2 (3 planes for red, 3 
planes for green, and 2 planes for blue). This colormap would have 
red_max = 7, green_max = 7, and blue_max = 3. 


An alternate allocation that uses only 216 colors is red_max = 5, green_max 
= 5, and blue_max=5. 


Specifies the scale factors used to compose a full pixel value. 
Specifies the scale factors used to compose a full pixel value. 
Specifies the scale factors used to compose a full pixel value. 


For a 3/3/2 allocation red_mult might be 32, green_mult might be 4, and 
blue_mult might be 1. 


For a 6-colors-each allocation, red_mult might be 36, green_mult might be 
6, and blue_mult might be 1. 


Specifies the base pixel value used to compose a full pixel value. The 
base_pixel field value is usually obtained from the XAllocColorPlanes 
subroutine. 


Given integer red, green, and blue coefficients in the appropriate ranges, you can compute a 
corresponding pixel value by using the following expression: 


2 * red mult + g * green_mult + b * blue _ mult + base_pixel 
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For GrayScale colormaps, only the colormap, red_max, red_mult, and base_pixel fields are 
defined. The other fields are ignored. Compute a gray-scale pixel value by using the 
following expression: 


gray * red mult + base_pixel 





XSegment Data Structure 


typedef struct { 
short xl, x2, yl, y2; 
} XSegment; 


All x and y fields are 16-bit signed integers. Do not generate coordinates and sizes out of the 
16-bit ranges because the protocol has only 16-bit fields for these values. For example, the 
rectangle {0,0,50000,1} references the coordinates x > = 49,999, and y = 0. This cannot be 
represented in 16 bits and the results are not defined. 


Related Information 
The XDrawLine subroutine, XDrawLines subroutine, XDrawRectangle subroutine, 
XDrawRectangles subroutine, XDrawSegments subroutine. 


The PolySegment protocol request. 


XRectangle Data Structure 


typedef struct { 

Short x, y;3 

unsigned short width, height; 
} XRectangle; 


All x and y fields are 16-bit signed integers. The width and height fields are 16-bit unsigned 
integers. Do not generate coordinates and sizes out of the 16-bit ranges because the 
protocol has only 16-bit fields for these values. For example, the rectangle {0,0,50000, 1} 
references the coordinates X > = 49,999, and Y = 0. This cannot be represented in 16 bits 
and the results are not defined. 


Related Information 
The XDraw Line subroutine, XDrawLines subroutine, XDrawRectangle subroutine, 
XDrawRectangles subroutine, XDrawSegments subroutine. 


The PolyRectangle protocol request 


XPoint Data Structure 


typedef struct { 
short x, y, 
} XPoint; 


All x and y fields are: 16-bit signed integers. Do not generate coordinates and sizes out of the 
16-bit range because the protocol has only 16-bit fields for these values. 
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Related Information 
~The XDrawPoint subroutine, XDrawPoints subroutine. 


XArc Data Structure 


typedef struct { 
short x, y; 
unsigned short width, height; ; 
short anglel, angle2; /* Degrees multiplied by 64 */ 
} XArc; 


All x and y fields are 16-bit signed integers. The width and height fields are 16-bit unsigned 
integers. Your application should not generate coordinates and sizes out of the 16-bit ranges 
because the protocol has only 16-bit fields for these values. 


Related Information 
The XDrawArc subroutine, XDrawArcs subroutine. 


XCharStruct Data Structure 


typedef struct { 


short lbearing; /* origin to left edge of raster */ 

short rbearing; /* origin to right edge of raster */ 

short width; /* advance to next character’s 
original */ 

short ascent; /* baseline to top edge of raster */ 

short descent; /* baseline to bottom edge of 


raster */ 
unsigned short attributes; /* per character flags (not 
predefined) */ 
} XCharStruct; 


The XCharStruct data structure defines the bounding box of a single character, a string, or 
the overall characteristics of a font. A nonexistent character is represented with all fields of 
the XCharStruct data structure set to the value of 0. Any of the fields of the XCharStruct 
data structure can be negative. | 


The fields of the XCharStruct data structure are defined as follows: 


Ibearing Specifies the extent of the left edge of the character ink from the origin. 
rbearing Specifies the extent of the right edge of the character ink from the origin. 
- width Specifies the logical width of the character. If the width field is negative, the 
next character is placed to the left of the current origin. 
ascent Specifies the extent of the top edge of the character ink from the origin. 
descent Specifies the extent of the bottom edge of the character ink from the origin. 


If the baseline is at the y coordinate y, the logical extent of the font is 
inclusive between the y coordinate values (y — font.ascent) and 
(y + font.descent — 1). Typically, the minimum interline spacing 
between rows of text is given by ascent + descent. 
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For a character origin at [x, y], the bounding box of a character in terms of 
XCharStruct components, is a rectangle: . 


The upper-left corner is: 


[x + lbearing, y — ascent] 
The width is: 
rbearing — lbearing 
The height is: 
ascent + descent 
The origin for the next character is defined as: 
[x + width, y] 


The baseline is logically viewed as being immediately below 
non-descending characters. When the descent field is zero, only pixels with 
y coordinates less than y are drawn. The origin is logically viewed as being 
concident with the left edge of a non-kerned character. 


When lbearing is the value of 0, no pixels with the X-coordinate less than 
x are drawn. Any of these values can be negative. 


attributes Specifies the per character flags. The X protocol does not define the 
interpretation of the attributes field. 


The baseline (the y position of the character origin) is logically viewed as being the scan line 
just below nondescending characters. When descent is 0, only pixels with Y coordinates less 
than y are drawn, and the origin is logically viewed as being coincident with the left edge of a 
nonkerned character. When /bearing is zero, no pixels with X coordinates less than x are 
drawn. Any of the XCharStruct metric members could be negative. If the width is negative, 
the next character will be placed to the left of the current origin. The X protocol does not 
define the interpretation of the attributes member in the XCharStruct structures. A 
nonexistent character is represented with all members of its XCharStruct structure set to 
zero. 





XFontProp Data Structure 


typedef struct { 

Atom name; 

unsigned long card32; 
} XFontProp; 


The XFontProp data structure describes a font property. A pointer to a list of these 
properties is included in the XFontStruct data structure. 


XChar2b Data Structure 


typedef struct { /* normal 16-bit characters are 2 bytes */ 
unsigned char bytel; 
unsigned char byte2; 

} XChar2b; 


5—86 AIX User Interface Programming Concepts 


The XChar2b data structure is used in the Xlib library subroutines that use 2-byte matrix 
fonts. 


Enhanced X-Windows supports both single byte per character and two bytes per character 
text operations. Either form can be used with a font, but a single byte per character text 
request can specify a single byte only, that is, the first row of a two-byte font. A two-byte font 
is similar in concept to a two-dimensional matrix of defined characters. 


byte? Specifies the range of defined rows. 
byte2 Defines the range of defined columns of the font. 


Single byte per character fonts have no rows defined. The byte2 range specified in the 
structure defines a range of characters. 


~ XFontStruct Data Structure 


The XFontStruct data structure contains all the information for the font, including font 
specific information and a pointer to an array of XCharStruct data structures for the 
characters contained in the font. If characters are undefined or nonexistent, the defau/t_char 
field is used. If the font has characters all the same size, only the information in the 
min_bounds and max_bounds fields is used. 


typedef struct { 


XExtData *Ext_data; /* hook for extension to hang 
data*/ 

Font fid; /* Font ID for this font */ 

unsigned direction; /* hint about the direction font 


is painted */ 
unsigned min_char_or_byte2; /* first character */ 
unsigned max_char_or_byte2; /* last character */ 


unsigned min_bytel; /* first row that exists */ 

unsigned max_bytel; /* last row that exists */ 

Bool all_chars_exist; /* flag if all characters have 
nonzero size */ 

unsigned default_char; /* char to print for undefined 
character */ 

int n_properties; /* how many properties there are */ 

XFontProp *properties; /* pointer to array of additional 
properties */ 

XCharStruct min_bounds; /* minimum bounds over all 
existing char */ 

XCharStruct max_bounds; /* maximum bounds over all 
existing char */ 

XCharStruct *per_char; /* first char to last char 
information */ 

int ascent; /* logical extent above baseline 
for spacing */ 

int descent; /* logical decent below baseline 


for spacing */ 
} XFontStruct; 


The fields of the XFontStruct data structure include the following: 
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direction 


min_byte1 
max_byte1 


min_char_or_byte2 


per_char 


all_chars_exist 


default_char 


min_bounds 


max_bounds 


Provides a hint as. to what most XCharStruct elements have in 
terms of character-width metric. The Core protocol does not support 
vertical text. The direction field can be set to one of the following: 


FontLeftToRight Specifies a positive character-width metric. 
FontRightToLett . Specifies a negative character-width metric. 
Indicates the first row that exists. 

Indicates the last row that exists. 


Specifies the linear character index of the last element. If the 
min_byte1 and max_byte1 fields are both the value of 0, then the 
max_char_or_byte2 field specifies the linear character index 
corresponding to the first element of the per_char field array. If 
either the min_byte1 or max_byte7 field is nonzero, then both the 
min_char_or_byte2 and max_char_or_byte2 fields are less than 
256, and the two-byte character index values corresponding to the 
per_char field array element N (counting from 0) are: 


bytel = N/D + min_bytel 
byte2 = N\D + min_char_or_byte2 
where: | | 
D = max_char_or_byte2 — min_char_or_byte2 + 1 
/ = integer division 
\ = integer modulus 


Specifies information about each character. If the per_char field is 
the value of NULL, ail glyphs between the first and last character, 
indexes inclusive, have the same information as given by both the 
min_bounds and max_bounds fields. 


If the all_chars_exist field is the value of True, all characters in the 
per_char field array have nonzero bounding boxes. 


Specifies the character to use when an undefined or nonexistent 
character is specified by the client. The default_charis a 16-bit 
character. For a font using 2-byte matrix format, the default_char 
has byte? in the most-siagnificant byte and byie2 in ine 
least-significant byte. 


If the default_char specifies an undefined or nonexistent character, 
no printing is performed. 


Specifies the smallest rectangle enclosing the shape obtained by 
superimposing all of the characters at the same origin [x,y]. 


Specifies the most extreme values of each individual XCharStruct 
component over all elements of this array which ignores nonexistent 
characters. The bounding box of the font is defined as follows: 


The upper-left coordinate is: 


[x + min_bounds.lbearing, y ~— max_bounds.ascent] 
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The x and y coordinates are the baseline coordinates of the box, 
relative to the origin. 


The width is: 

max _bounds.rbearing — min_bounds.lbearing 
The height is: 

max_bounds.ascent + max_bounds.descent 


ascent Specifies the logical extent of the font above the baseline that is 
used for determining line spacing. Specific characters can extend 
beyond this. 


descent Specifies the logical extent of the font at or below the baseline that 
is used for determining line spacing. Specific characters may extend 
beyond this. 


The interpretation of the attributes field in the XCharStruct data structure is not defined by 
the core protocol. A nonexistent character is represented with members of the XCharStruct 
data structure set to the value of 0. 


A font is not guaranteed to have any properties. The interpretation of the property value, for 
example, INT32, CARD32, must be derived from a prior knowledge of the property. When 
possible, fonts should have the properties listed in the following table. (Atom names are 
case-sensitive.) The following built-in property atoms are in <X11/Xatom.h>. 


Property Name 


MIN_SPACE The minimum interword spacing, specified in 








Type 










pixels. 


unsigned |The normal interword spacing, specified in pix- 
els. 

The maximum interword spacing, specified in 
pixels. 


The additional spacing at the end of sen- 
tences, specified in pixels. 

SUPERSCRIPT_X 

SUPERSCRIPT_Y 








integers | The offset, specified in pixels from character 
origin where superscripts should begin. If the 
origin is at [x,y], then superscripts should 

begin at [x + SUPERSCRIPT _X, y — SU- 


PERSCRIPT Y]. 




















SUBSCRIPT_X 
SUBSCRIPT_Y 


Offset, specified in pixels, from character origin 
where subscripts should begin. If origin is at 
[x,y], then subscripts should begin at 

[x + SUPERSCRIPT X, y + SUPER- 
SCRIPT_Y]. 


The y offset, specified in pixels from the base- 
line to the top of an underline. If the baseline is 
the y coordinate y, then the top of the under- 

line is at (y + UNDERLINE POSITION). 


integers 















UNDERLINE_POSITION | integer 
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UNDERLINE_THICKNESS Thickness of the underline, specified in pixels. 


STRIKEOUT_ASCENT Vertical extents, specified in pixels, for boxing 
STRIKEOUT_DESCENT or voiding characters. If the baseline is at 
Y-coordinate y, then the top of the strikeout 
box is at(y — STRIKEOUT_ASCENT), and the 
height of the box is (STRIKEOUT_AS- 

CENT + STRIKEOUT DESCENT). 


ITALIC_ANGLE integer The angle of the dominant staffs of characters 
in the font, in degrees scaled by 64, relative to 
the three o’clock position from the character 
origin, with positive indicating counterclock- 
wise motion. 


X_ ee et ee 1 ex as in TeX, but expressed in pixels. Often 
ee height of lowercase x. 

a WIDTH integer 1 emas in TeX, but expressed in pixels. Often 
the width of the digits 0-9. 


Snape HEIGHT integer The y offset, specified in pixels from the base- 
line to the top of the capital letters, ignoring 
accents. If the baseline is at the y coordinate y, 
then the top of the uppercase letters is at 
(y — CAP_HEIGHT). 


ee st unsigned | The weight or boldness of the font, expressed 
as a value between 0 and 1000. 
POINT_ Sauepainan! unsigned | The point size of the font at the ideal resolu- 
tion, expressed in 1/10ths of points. There are 
72.27 points to the inch. 
RESOLUTION The number of pixels per point, expressed in 
1/100ths, at which the font was created. 
Related Information 
The XFreeFont subroutine, XFreeFontinfo subroutine, XFreeFontNames subroutine, 
XFreeFontPath subroutine, XGContextFromGC subroutine, XGetFontPath subroutine, 
XGetFontProperty subroutine, XListFonts subroutine, XListFontsWithInfo subroutine, 
XLoadFont subroutine, X_LoadQueryF ont subroutine, XQuery TextExients subroutine, 
XQueryTextExtents16 subroutine, XSetFontPath subroutine, XTextExtents subroutine, 


XTextExtents16 subroutine, XTextWidth subroutine, XTextWidth16 subroutine, 
XUnloadFont subroutine. 







































XTextitem Data Structure 


typedef struct { 
char *chars; /* pointer to string */ 
int nchars; /* number of characters */ 
int delta; /* delta between strings along the x axis */ 
Font font; /* Font to print it in, None does not change */ 
} XTextItem; 
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xr 


If the font field is the value of None, the font is changed before printing and is stored in the 
GC. If an error is generated during text drawing, the font in the GC is undefined. 


Related Information 
The XDrawText subroutine 


XTextltem16 Data Structure 


typedef struct { 
XChar2b *chars; /* pointer to two byte characters */ 


int nchars; /* number of characters */ 
int delta; . /* delta between strings along the x axis */ 
Font font; /* font to print it in, None does not change */ 


_ } XTextIteml6é; 


The fields of the XTextitem16 data structure are as follows: 


chars Specifies a pointer to two-byte characters. The chars field of the 
XTextitem16 data structure is of type XChar2b. The X Server interprets 
each member of the XChar2b structure as a 16-bit number that has been 
transmitted by most-significant byte first. The byte? field of the XChar2b 
structure is taken as the most-significant byte. 


nchars Specifies the number of characters. 
delta Specifies the delta between strings along the x axis. 
font Specifies the font to print it in. If the font field is the value of None, the font 


is changed before printing and stored in the GC. If an error is generated 
during text drawing, the font in the GC is undefined. 


Related Information 
The XDrawText16 subroutine 
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XImage Data Structure 


typedef struct XImage { 


int width, height; /* size of image */ 

int xoffset; /* number of pixels offset in X 
direction */ 

int format; /* XYBitmap, XYPixmap, ZPixmap */ 

char *data; /* pointer to image data */ 

int byte_order; /* data byte order, MSBFirst or 
LSBFirst */ 

int bitmap _unit; /* quant. of scanline 8, 16, 32 */ 

int bitmap_bit_order; /* MSBFirst or LSBFirst */ 

int bitmap_pad; /* 8, 16, 32 either XYPixmap or 
ZPixmap */ 

int depth; /* depth of image */ 

int bytes_per line; /* accelerator to next line */ 

int bits_per_pixel; /* bits per pixel (ZPixmap) */ 

unsigned long red_mask; /* bits in z arrangement */ 


unsigned long green_mask; /* bits in z arrangement */ 
unsigned long blue_mask; /* bits in z arrangement */ 


char *obdata; /* hook for the object routines to 
/* hang on */ 
struct funcs { /* image manipulation routines */ 


struct XImage *(*create_image)(); 
int (*destroy_image)(); 
unsigned long (*get_pixel)(); 
int (*put_pixel)(); 
struct _XImage *(*sub_image)(); 
int (*add_pixel)(); 

} £; 


} XImage; 


The Ximage data structure describes an image as it exists in client memory. You can 
request changes to some fields in this data structure, for example, height, width, and xoffset. 
These changes create a subset of the image. Other fields of this structure, for example, 
byte_order and bitmap_unit, are characteristic of both the image and the server. If these 
fields differ between the image and the server, XPutimage makes the appropriate 
conversions. 


If the image is formatted as an XYPixmap, the first byte of the first line of plane n must be 
located at the address of the client as follows: 


(data + (n * height * bytes_per line)). 
Related Information 
The XAddPixel subroutine, XCreatelmage subroutine, XDestroylmage subroutine, 


XGetimage subroutine, XGetPixel subroutine, XGetSublmage subroutine, XPutimage 
subroutine, XPutPixel subroutine, XSubIlmage subroutine. 


5—92 AIX User Interface Programming Concepts 


SS 


XKeyboardControl Data Structure 


#define KBKeyClickPercent (1L<<0) 


#define KBBellPercent (1L<<1) 
#define KBBellPitch ( 1L<<2) 
#define KBBellDuration (1L<<3) 
#define KBLed (1L<<4) 
#define KBLedMode (1L<<5) 
#define KBKey (1L<<6) 
#define KBAutoRepeatMode (1L<<7) 


typedef struct { 


int key _click_percent; 
int bell_percent; 


int bell pitch; 


int bell duration; 


int led; 


int led_mode; 


int key; 


/* LedModeOn, LedModeOff */ 


int auto_repeat_mode; /* AutoRepeatModeOff, AutoRepeatModeOn, 


AutoRepeatModeDefault */ 


} XKeyboardControl; 


The fields of the XKeyboardControl data structure include the following values: 


key_click_percent 


bell_percent 


bell_pitch 


bell_duration 


led 


led_mode 


key 


auto_repeat_mode 


Sets the volume for key clicks between 0 (off) and 100 (loud) 
inclusive, if possible. A setting of -1 restores the default. Other 
negative values generate an error. 


Sets the base volume for the bell between 0 (off) and 100 (loud) 
inclusive, if possible. A setting of -1 restores the default. Other 
negative values generate an error. 


Sets the pitch, specified in hertz (Hz) of the bell, if possible. A 
setting of -1 restores the default. Other negative values generate an 
error. 


Sets the duration of the bell (in milliseconds), if possible. A setting 
of -1 restores the default. Other negative values generate an error. 


Specifies the LED member. If the /led_mode and the /ed fields are 
specified, the state of those LEDs is changed, if possible. This 
occurs where the /ed field is the ordinal number of the LED to be 
changed and not a mask. 


The state of all LEDs is changed, if possible. At most 32 LEDs, 
numbered from 1, are supported. If an LED is specified without 
led_mode, a BadMatch error is generated. No standard 
interpretation of LEDs is defined. 


Specifies a key on the keyboard. 


Specifies the auto repeat mode. If the auto_repeat_mode and the 
key fields are specified, the auto_repeat_mode of that key is 
changed, if possible. If only the auto_repeat_mode field is specified, 
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the global auto_repeat_mode for the entire keyboard is changed, if 
possible, and does not affect the per key settings. If a key is 
specified without the auto_repeat_mode field, a BadMatch error is 
generated. OO 


The order in which controls are verified and altered is server-dependent. If an error is 
generated, a subset of the controls may have been altered. 





XKeyboardState Data Structure 


typedef struct { 
int key_click_percent; 
int bell_percent; 
unsigned int bell pitch, bell_duration; 
unsigned long led_mask; 
int global_auto_repeat; 
char auto_repeats[32]; 
} XKeyboardState; 


For the LEDs, the least-significant bit of the /ed_mask field corresponds to LED 1, and each 
bit in /ed_mask that is set to 1 indicates an LED that is lit. 


The auto_repeats field is a bit vector. Each bit indicates that auto-repeat is enabled for the 
corresponding key. The vector is represented as 32 bytes. Byte N (from 0) contains the bits 
for keys 8N to 8N+7, with the least-significant bit in the byte representing key 8N. 


The global_auto_repeat field can be set to the value of AutoRepeatModeOn or 
AutoRepeatModeOff. 


Related Information 
The XAutoRepeatOn subroutine, XBell subroutine, XChangeKeyboardControl 
subroutine, XGetKeyboardControl subroutine, XGetPointerMapping subroutine, 
XQueryKeymap subroutine, XSetPointerMapping subroutine. 


XModifierKeymap Data Structure 


typedef struct { 


int max_keypermod; /* Max number of keys per 
modifier of this server */ 
KeyCode *modifiermap; /* An 8 by max_keypermod array 


of the modifiers */ 
} XModifierKeymap; 


Related Information 
The <X11/keysym.h> header file, <X11/keysymdef.h> header file 


The XChangeKeyboardMapping subroutine, XDeleteModifiermapEntry subroutine, 
XFreeModifiermap subroutine, XGetKeyboardMapping subroutine, 
XGetModifierMapping subroutine, XInsertmodifiermapEntry subroutine, XLookupString 
subroutine, XNewModifiermap subroutine, XSetModifierMapping subroutine. 
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XHostAddress Data Structure 


typedef struct { 


int family; /* for example FamilyInternet */ 
int length; /* length of address, in bytes */ 
char *address; /* pointer to where to find the address */ 


} XHostAddress; 


The fields of the XHostAddress data structure are: 


family Specifies which protocol address family to use (for example, the TCP/IP or 
UNIX domain). The family symbols are defined in the <X11/X.h> header file. 

length Specifies the length of the address in bytes. 

address Specifies a pointer to the address. 


Related Information 
The <X11/X.h> header file, /etc/X?.hosts file. 


The XAddHost subroutine, XAddHosts subroutine, XListHosts subroutine, XRemoveHost 
subroutine, XRemoveHosts subroutine. 
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XAnyEvent Data Structure 
For each event type, a corresponding structure is declared in the <X11/Xlib.h> header file. 


typedef struct { 


int type; 
unsigned long serial; /* Number of last request processed 
by the server */ 
Bool send_event; /* True if this came from a SendEvent 
. request */ 
Display *display; /* Display the event was read from */ 


Window window; 
} XAnyEvent: 


All the event structures have the following common fields. 

type Set to the event type constant name that uniquely identifies the event 
type. For example, when the X Server reports a GraphicsExpose 
event to a client application, the event sends an 


XGraphicsExposeEvent structure with the type member set to 
GraphicsExpose. 


display Set to a pointer to the display the event was read on. 


send_event Set to the value of TRUE if the event was generated by an 
XSendEvent request. 


serial Set to the serial number reported in the protocol but expanded from 
the 16-bit least significant bits to a full 32-bit value. 


Related Information 
The <X11/Xlib.h> header file. 
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XEvent Data Structure 


typedef union xXEvent { 
int type /* Must not be changed */ 
XAnyEvent xany; 
XKeyEvent xkey; 
XButtonEvent xbutton; 
XMotionEvent xmotion; 
XCrossingEvent xcrossing; 
XFocusChangeEvent xfocus; 
XExposeEvent xexpose; 
XGraphicsExposeEvent xgraphicsexpose; 
XNoOExposeEvent xnoexpose; 
XVisibilityEvent xvisibility; 
XCreateWindowEvent xcreatewindow; 
XDestroyWindowEvent xdestroywindow; 
XUnmapEvent xunmap; 
XMapEvent xmap; 
XMapRequestEvent xmaprequest; 
XReparentEvent xreparent; 
XConfigureEvent xconfigure; 
XGravityEvent xgravity; 
XResizeRequestEvent xresizerequest; 
XConfigureRequestEvent xconfigurerequest; 
XCirculateEvent xcirculate; 
XCirculateRequestEvent xcirculaterequest; 
XPropertyEvent xproperty; 
XSelectionClearEvent xselectionclear; 
XSelectionRequestEvent xselectionrequest; 
XSelectionEvent xselection; 
XColormapEvent xcolormap; 
XClientMessageEvent xclient; 
XMappingEvent xmapping; 
XErrorEvent xerror; 
XKeymapEvent xkeymap; 
long pad[24]; 

} XEvent; 


Related Information 
The <X11/Xlib.h> header file. 
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XButtonPressedEvent or XButtonReleasedEvent Data 


Structure 


typedef struct { 
int type; 
unsigned long serial; 
Bool send_event; 
Display *display; 
Window window; 
Window root; 
Window subwindow; 


Time time; 
int x, y; 


/* ButtonPress or ButtonRelease */ 

/* Number of the last request 
processed by the server */ 

/* True if this came from a 

SendEvent request */ 

/* The display the event was read 
from */ 

/* The event window it is reported 
relative to */ 

/* Root window that the event 
occurred on */ 

/* The child window */ 

/* Milliseconds */ 

/* Pointer x, y coordinates in the 
event window */ 


int x_root, y root; /* Coordinates relative to the root 
window */ 

unsigned int state; /* Key or button mask */ 

unsigned int button; /* Detail */ 


Bool same_screen; 
} XButtonEvent; 


/* Same screen flag */ 


typedef XButtonEvent XButtonPressedEvent}; 
typedef XButtonEvent XButtonReleasedEvent}; 


The fields for these structures are defined as follows: 


type 


window 


root 


x_root 


Set to the event type constant name that uniquely identifies the 
event type. For example, when the X Server reports a 
GraphicsExpose event to a client application, the event sends an 
XGraphicsExposeEvent structure with the type field set to 
GraphicsExpose. 


Set to a pointer to the display the event was read on. 


Sei io the value of TRUE if the event was generated by an 
XSendEvent request. 


Set to the serial number reported in the protocol but expanded from 
the 16-bit least significant bits to a full 32-bit value. 


The window ID of the window on which the event was generated. 
This is the event window. The X Server uses this window to report 
the event. 


The window ID of the root window of the source. 


This is set to the x pointer coordinate relative to the origin of the root 
window at the time of the event. 
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y_root 


same_screen 


This is set to the y pointer coordinate relative to the origin of the root 
window at the time of the event. 


Indicates if the event window is on the same screen as the root 
window. This parameter can be: 


TRUE If the event and root windows are on the same screen. 

FALSE If the event and root windows are not on the same 

screen. 

subwindow Can be one of the following: 

e The child of the event window that is an ancestor of or is the 
source member, if the event window is on the same screen as 
the root window. 

e Otherwise, the subwindow is the value of None. 

x Can be one of the following: 

e ifthe event window is on the same screen as the root window, 
the x coordinate is set to the coordinate relative to the event 
window’s origin 

e Otherwise, X is the value of 0. 

y Can be one of the following: 

e lf the event window is on the same screen as the root window, 
the y coordinate is set to the coordinate relative to the event 
window’s origin 

e Otherwise, Yis the value of 0. 

time The time that the event was generated. The time is expressed in 
milliseconds since the server reset. 

State Indicates the state of the pointer buttons and modifier keys just prior 
to the event. The X Server can set this member to the 
bitwise-inclusive OR of one or more of the following button or 
modifier key masks: 

Button1 Mask ShiftMask Mod1Mask 

Button2Mask LockMask Mod2Mask 

Button3Mask ControiMask Mod3Mask 

Button4Mask Mod4Mask 

Button5Mask Mod5Mask 

button This represents the pointer buttons that changed state for the 


XButtonPressedEvent and XButtonReleasedEvent data 
structures, and can be set to one or more of the following button 
names: Button1, Button2, Button3, Button4, Buttons. 


Related Information 
The ButtonPress protocol event, ButtonRelease protocol event. 
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XKeyPressedEvent or XKeyReleasedEvent Data Structure 


typedef struct { 


int type; /* KeyPress or KeyRelease */ 

unsigned long serial; /* Number of the last request 
processed by the server */ 

Bool send_event; /* True if this came from a SendEvent 
request */ 

Display *display; /* The display the event was read 


Window window; 


Window root; 


from */ 

/* The event window it is reported 
relative to */ 

/* Root window that the event 
occurred on */ 


Window subwindow; /* The child window */ 


Time time; 
int x, y; 


/* Milliseconds */ 
/* Pointer x, y coordinates in the 
event window */ 


int x_root, y root; /* Coordinates relative to the root 
window */ 

unsigned int state; /* Key or button mask */ 

unsigned int keycode; /* Detail */ 

Bool same_screen; /* Same screen flag */ 


} XKeyEvent; 


typedef XKeyEvent XKeyPressedEvent; 
typedef XKeyEvent XKeyReleasedEvent; 


The fields for these structures are defined as follows: 


type 


display 


send_event 


serial 


window 


root 


x_root 


y_root 


Set to the event type constant name that uniquely identifies the 
event type. For example, when the X Server reports a 
GraphicsExpose event to a client application, the event sends an 
XGraphicsExposeEvent data structure with the type field set to 
GraphicsExpose. 


Set to a pointer to the display the event was read on. 


Set to the value of TRUE if the event was generated by an 


XSendEvent request. 


Set to the serial number reported in the protocol but expanded from 
the 16-bit least significant bits to a full 32-bit value. 


The window ID of the window on which the event was generated. 
This is the event window. The X Server uses this window to report 
the event. 


The window ID of the root window of the source. 


This is set to the x pointer coordinate relative to the origin of the root 
window at the time of the event. 


This is set to the y pointer coordinate relative to the origin of the root 
window at the time of the event. 


5-100 AIx User Interface Programming Concepts 


same_screen 


subwindow 


time 


state 


_ keycode 


Related Information 


Indicates if the event window is on the same screen as the root 
window. This field can be either of the following values: 


TRUE If the event and root windows are on the same screen. 
FALSE If the event and root windows are not on the same 
screen. 


Can be one of the following: 


e The child of the event window that is an ancestor of or is the 
source member, if the event window is on the same screen as 
the root window. 


e Otherwise, the subwindow field has the value of None. 
Can be one of the following: 


e The x coordinate relative to the origin of the event window if the 
root window is on the same screen as the event window. 


e Otherwise, the x field has the value of 0. 
Can be one of the following: 


e The y coordinate relative to the origin of the event window if the 
root window is on the same screen as the event window. 


e Otherwise, the y field has the value of 0. 


The time that the event was generated. The time is expressed in 
milliseconds since the server reset. 


Indicates the state of the pointer buttons and modifier keys just prior 
to the event. The X Server can set this member to the bitwise 
include OR of one or more of the following button or modifier key 
masks: 


Button! Mask ShiftMask 


Mod1Mask 
Button2Mask LockMask Mod2Mask 
Button3Mask ControiMask Mod3Mask 
Button4Mask Mod4Mask 
Button5Mask Mod5Mask 


This is set to a number that represents a physical key on the 
keyboard for the XKeyPressedEvent and XKeyReleasedEvent 
data structures. 


The KeyPress event, KeyRelease event. 


Chapter 5. Enhanced X-Windows 5—101 





XPointerMovedEvent Data Structure 


typedef struct { 


int type; /* MotionNotify */ 

unsigned long serial; /* Number of the last request 
processed by the server */ 

Bool send_event; /* True if this came from a 
SendEvent request */ 

Display *display; /* The display the event was read 


Window window; 


Window root; 


from */ 

/* The event window it is reported 
relative to */ 

/* Root window that the event 
occurred on */ 


Window subwindow; /* The child window */ 


Time time; 


/* Milliseconds */ 


int x, y;3 /* Pointer x, y coordinates in the 
event window */ 

int x_root, y_root; /* Coordinates relative to the root 
window */ 

unsigned int state; /* Key or button mask */ 

unsigned int keycode; /* Detail */ 


char is_hint; 


/* Detail */ 


Bool same_screen; /* Same screen flag */ 


} XMotionEvent; 


typedef XMotionEvent XPointerMovedEvent} 


The fields for the XPointerMovedEvent data structure are defined as follows: 


type 


display 


send_event 


serial 


window 


root 


x_root 


y_root 


Set to the event type constant name that uniquely identifies the 
event type. For example, when the X Server reports a 
GraphicsExpose event to a client application, the event sends an 
XGraphicsExposeEvent structure with the type field set to the 
value of GraphicsExpose. 


Set to a pointer to the display the event was read on. 


Set to the value of TRUE if the event was generated by an 


XSendEvent request. 


Set to the serial number reported in the protocol but expanded from 
the 16-bit least significant bits to a full 32-bit value. 


The window ID of the window on which the event was generated. 
This is the event window. The X Server uses this window to report 
the event. 


The window ID of the root window of the source. 


This is set to the x pointer coordinate relative to the origin of the root 
window at the time of the event. og 


This is set to the y pointer coordinate relative to the origin of the root 
window at the time of the event. 


5—102 AIX User Interface Programming Concepts 


same_screen 


subwindow 


time 


State 


is_hint 


Related Information 


Indicates if the event window is on the same screen as the root 
window. This field can be either of the following values: 


TRUE lf the event and root windows are on the same screen. 
FALSE lf the event and root windows are not on the same 
screen. 


Can be one of the following: 


e The child of the event window that is an ancestor of or is the 
source member, if the event window is on the same screen as 
the root window. 


e Otherwise, the subwindow field has the value of None. 
Can be one of the following: 


e The x coordinate relative to the origin of the event window if the 
source window and the event window are on the same screen. 


e Otherwise, the x field has the value of 0. 
Can be one of the following: 


e The y coordinate relative to the origin of the event window if the 
source window and the event window are on the same screen. 


e Otherwise, the y field has the value of 0. 


The time that the event was generated. The time is expressed in 
milliseconds since the server reset. 


Indicates the state of the pointer buttons and modifier keys just prior 
to the event. The X Server can set this member to the bitwise- 
inclusive OR of one or more of the following button or modifier key 


masks: 

Button1 Mask ShiftMask Mod1Mask 
Button2Mask LockMask Mod2Mask 
Button3Mask ControlMask Mod3Mask 
Button4Mask Mod4Mask 
Button5Mask Mod5Mask 


This can be set to the value of NotifyNormal or NotifyHint for the 
XPointerMovedEvent data structure. 


The MotionNotify event. 
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XCrossingEvent or XEnterWindowEvent or 
XLeaveWindowEvent Data Structures 


typedef struct { 
int type; 


unsigned long serial; 


Bool send_event; 
Display *display; 
Window window; 
Window root; 
Window subwindow; 
Time time; 

int x, y; 

int x_root, y_root; 


int mode; 


int detail; 


Bool same_screen; 

Bool focus; 

unsigned int state; 
} XCrossingEvent; 


/* EnterNotify or LeaveNotify */ 

/* Number of the last request 
processed by the server */ 

/* True if this came from a 
SendEvent request */ 

/* The display the event was read 
from */ j 

/* The event window it is 
reported relative to */ 

/* Root window that the event 
occurred on */ 

/* The child window */ 

/* Milliseconds */ 

/* Pointer x, y coordinates in 
the event window */ 

/* Coordinates relative to the 
root window */ 

/* NotifyNormal, NotifyGrab, 
NotifyUngrab */ | 

/* NotifyAncestor, NotifyVirtual, 
NotifyInferior, 
NotifyNonlinear, 
NotifyNonlinearVirtual */ 

/* Same screen flag */ 

/* Boolean focus */ 

/* Key or button mask */ 


typedef XCrossingEvent XEnterWindowEvent; 
typedef XCrossingEvent XLeaveWindowEvent; 


The fields of the XCrossingEvent, XEnterWindowEvent, and XLeaveWindowEvent data 


structures are as follows: | 


type Set to the event tyne 


constant name thai uniquely identifies the event 


type. For example, when the X Server reports a GraphicsExpose 
event to a client application, the event sends an 
XGraphicsExposeEvent structure with the type field set to 


GraphicsExpose. 


display Set to a pointer to the display the event was read on. 


send_event Set to the value of TRUE if the event was generated by an 
XSendEvent request. 


serial Set to the serial number reported in the protocol! but expanded from 
the 16-bit least significant bits to a full 32-bit value. 


window The window ID of the window on which the EnterNotify or 
LeaveNotify event was generated. This window is the event window. 
The X Server uses this window to report the events. 
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SLY 


root 


subwindow 


subwindow 


time 


x_root 


y_root 


Same_screen 


focus 


state 


The ID of the root window on which the event occurred. 


in a LeaveNotify event, if a child of the event window contains the 
initial position of the pointer, the subwindow field is set to that child. 
Otherwise, the X Server sets the subwindow field to the value of None. 


In an EnterNotify event, if a child of the event window contains the 
final pointer position, the subwindow is set to that child. Otherwise, it is 
set to the value of None. 


The time (in milliseconds) the event was generated. 


The x pointer position in the event window. This position is always the 
final position of the pointer, not the initial position of the pointer. 


The y pointer position in the event window. This position is always the 
final position of the pointer, not the initial position of the pointer. 


If the event window is on the same screen as the root window, x and y 
are the pointer coordinates relative to the origin of the event window. 
Otherwise, the x and y fields are set to the value of 0. 


Set to the x pointer coordinate relative to the origin of the root window 
at the time of the event. 


Set to the y pointer coordinate relative to the origin of the root window 
at the time of the event. 


Indicates if the event window is on the same screen as the root 
window. The same_screen field can be either of the following values: 


True The event and root windows are on the same screen. 


False The event and root windows are not on the same screen. 


Indicates whether the event window is the focus window or an inferior 
of the focus window. The focus field can be either of the following 
values: 


True The event window is the focus window or an inferior of the 
focus window. 
False The event window is neither the focus window nor an 


inferior of the focus window. 


Indicates the state of the pointer buttons and modifier keys 
immediately prior the event. The X Server can set this field to the 
bitwise-inclusive OR of one or more of the following button or modifier 
key mask values. 


Button1Mask ShiftMask Mod1Mask 
Button2Mask LockMask Mod2Mask 
Button3Mask ControlMask Mod3Mask 
Button4Mask Mod4Mask 
Button5Mask Mod5Mask 
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mode indicates if the events are normal events or pseudo motion events 
when a grab activates, or when a grab deactivates. The X Server can 
set the mode field to one of the following values: 


NotifyNormal 
NotifyGrab 
NotifyUngrab. 

detail Indicates the notify detail can be set to one of the following values: 
NotifyAncestor NotifyVirtual | 
Notifyinferior NotifyNonlinear 


NotifyNonlinearVirtual 


Related Information 
The EnterNotify event, LeaveNotify event. 


The XChangeActivePointerGrab subroutine, XGrabKeyboard subroutine, XGrabPointer 
subroutine, XUngrabPointer subroutine. 


XFocusChangeEvent or XFocusinEvent or XFocusOutEvent 
Data Structures 


typedef struct { 
int type; /* FocusIn or FocusOut */ 
unsigned long serial; /* Number of the last request 
processed by the server */ 
Bool send_event; /* True if this came from a 
SendEvent request */ 
Display *display; /* The display the event was read 
from */ 
Window window; /* The window of the event */ 
int mode; /* NotifyNormal, NotifyGrab, 
NotifyUngrab */ 
int detail; /* NotifvyAncestor, NotifyVirtual, 
NotifyInferior, 
NotifyNonlinear, 
NotifyNonlinearVirtual, 
NotifyPointer, 
NotifyPointerRoot, 
NotifyDetailNone */ 
} XFocusChangeEvent}; 
typedef XFocusChangeEvent XFocusInEvent; 
typedef XFocusChangeEvent XFocusOutEvent; 


The fields of the XFocusChange, XFocusinEvent and XFocusOutEvent data structures 
include the following definitions: 


window Specifies the window ID of the window on which the Focusin or FocusOut 
event was generated. The X Server uses this window to report the event. 
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mode Specifies the type of focus event. The mode field can be set to one of the 
following values: 


NotifyNormal Specifies a normal focus event. 


NotifyWhileGrabbed Specifies a focus event while grabbed. 


NotifyGrab Specifies a focus event when a grab activates. 

NotifyUngrab Specifies a focus event when a grab deactivates. 
detail Indicates the notify detail depending on the event mode. The detail field can 

be one of the following values: 

NotifyAncestor - NotifyVirtual 

NotifyInferior NotifyNonlinear 

NotifyNonlinearVirtual NotifyPointer 

NotifyPointerRoot NotifyDetailNone 


All FocusOut events caused by a window unmap are generated after any UnmapNotify 
event, but the ordering of FocusOut events with respect to generated EnterNotify, 
LeaveNotify, VisibilityNotify, and Expose events is not constrained by the X protocol. 


Related Information 
The Focusin event, FocusOut event. 


The XGrabKeyboard subroutine, XUngrabKeyboard subroutine. 


XKeymapEvent Data Structure 


typedef struct { 


int type; . /* KeymapNotify */ 

unsigned long serial; /* Number of the last request 
processed by the server */ 

Bool send_event; /* True if this came from a 
SendEvent request */ 

Display *display; /* The display the event was 


read from */ 
Window window; 
char key vector[ 32]; 
}. XKeymapEvent; 


The fields of the XKeymapEvent data structure associated with this event include the 
following: 
window This is not used, but present for use with toolkit operations. 


key_vector Specifies the bit vector of the keyboard. Each bit indicates that the 
corresponding key is currently pressed. The vector is represented as 32 
bytes. Byte N (from 0) contains the bits for keys 8N to 8N+7 with the 
least significant bit in the byte representing key 8N. 
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Related Information 
The KeymapNotify event. 


XExposeEvent Data Structure 


typedef struct { 
int type; 
unsigned long serial; 


Bool send_event; 
Display *display; 
Window window; 
int x, y; 


int width, height: 
int count; 


} XExposeEvent; 


/* 


/* 


/* 


/* Expose */ 

Number of the last request 
processed by the server */ 
True if this came from a 
SendEvent request */ 

The display the event was read 
from */ 


If nonzero, at least this many 
more */ 


The fields of the XExposeEvent data structure include the following: 


window The window ID of the exposed (damaged) window. 


x Indicates the x coordinate of the rectangle. This coordinate is set relative to 
the origin of the drawable. 


y Indicates the y coordinate of the rectangle. This coordinate is set relative to 
the origin of the drawable. 


width Specifies the width extent of the rectangle. 

height Specifies the height extent of the rectangle. 

count Specifies the number of Expose events that should follow. The count field 
can be: 
0 "No Expose events will follow. (Applications not designed to 


optimize redisplay by distinguishing between subareas of a 
window redisolay entirely if the count field is the value of 9.) 


nonzero At least that number, and possibly more, Expose events will 
follow. (Applications not designed to optimize redisplay by 
distinguishing between subareas of a window, do not 
respond if the count field is a nonzero value.) 


Related Information 
The Expose event. 
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XGraphicsExposeEvent Data Structure 


typedef struct { 


int type; /* GraphicsExpose */ 
unsigned long serial; /* Number of the last request 
processed by the server */ 
Bool send_event; /* True if this came from a 
SendEvent request */ 
Display *display; /* The display the event was read 


from */ 


Drawable drawable; 


int x, y? 


int width, height: 

int count; /* If nonzero, at least this many 
more */ 

int major_code; /* core is CopyArea or CopyPlane */ 

int minor_code; /* Not defined in the core */ 


} XGraphicsExposeEvent} 


The XGraphicsExposeEvent data structure included the following fields: 


drawable 


major_code 


minor_code 


width 
height 


count 


Specifies the drawable {D of the destination region on which the graphics 
request is to be performed. 


Specifies the graphics request initiated by the client This field can have 
one of the following values: 


X_CopyArea Indicates that a call to the XCopyArea subroutine 
initiated the request. 


X_CopyPlane Indicates that a call to the XCopyPlane subroutine 
initiated the request. 


These constants are defined in the <X11/Xproto.h> file. 


Specifies the graphics request initiated by the client. This field, however, 
is not defined by the core X protocol and will have the value of 0 in these 
cases, although it may be used as an extension. 


Specifies the x coordinate of the upper left corner of the rectangle. This 
coordinate is relative to the origin of the drawable. 


Specifies the y coordinate of the upper left corner of the rectangle. This 
coordinate is relative to the origin of the drawable. 


Specifies the size (extent) of the rectangle. 
Specifies the size (extent) of the rectangle. 


Specifies the number of GraphicsExpose events to follow for the 
specified window. This field can have the following values: 


0 Indicates that no GraphicsExpose events will follow. 
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nonzero Indicates that at least that number, and possibly more, 
GraphicsExpose events will follow. — 


Related Information 
The GraphicsExposure event, NoExpose event. 


The XCopyArea subroutine, XCopyPlane subroutine, XCreateGC subroutine, 
XSetGraphicsExposures subroutine. 


XNoExposeEvent Data Structure 


typedef struct { 


int type; /* NoExpose */ 

unsigned long serial; /* Number of the last request 
processed by the server */ 

Bool send_event; /* True if this came from a SendEvent 

request */ 

Display *display; /* The display the event was read 
from */ 

Drawable drawable; 

int major_code; /* core is CopyArea or CopyPlane */ 

int minor_code; /* Not defined in the core */ 


} XNOExposeEventy; 


The XGraphicsExposeEvent and XNoExposeEvent data structures have the following 
common fields: 


drawable Specifies the drawable ID of the destination region on which the graphics 
request is to be performed. 


major_code Specifies the graphics request initiated by the client The major_code field 
can have either of the following values: 


X_CopyArea Indicates that a cail to the XCopyArea subroutine 
initiated the request. 


X_CopyPlane Indicates that a call to the XCopyPlane subroutine 
initiated the request. 


minor_code Specifies the graphics request initiated by the client. The minor_code 
field, however, is not defined by the core X protocol and will have the 
value of 0 in these cases, although it may be used as an extension. 


Related Information 
The <X11/Xproto.hs file. 
The GraphicsExpose event, NoExpose event. 


The XCopyArea subroutine, XCopyPlane subroutine, XCreateGC subroutine, 
XSetGraphicsExposures subroutine. 


5—110 AIX User Interface Programming Concepts 





XCirculateEvent Data Structure 


typedef struct { 


int type; /* CirculateNotify */ 

unsigned long serial; /* Number of last request processed 
by the server */ 

Bool send_event; /* True if this came from a SendEvent 
request */ 

Display *display; /* The display the event was read 
from */ 


Window event; 

Window window; 

int place; /* PlaceOnTop, PlaceOnBottom */ 
} XCirculateEvent; 


The XCirculateEvent data structure includes the following fields: 

type Specifies the event type, CirculateNotify. 

serial Specifies the number of the last request processed by the server. 
send_event Specifies True if this came from a SendEvent request. 

display Specifies the display that the event was read from. 


event Specifies the window on which the event was generated. This field is set to 


either the restacked window or its parent, depending on whether 
StructureNotify or SubstructureNotify was selected. 


window Specifies the window that was restacked. 


place Specifies the window position after the restack occurs. The place field can 
have either of the following values: 


PlaceOnTop Indicates that the window is now on top of all siblings. 


PilaceOnBottom Indicates that the window is now below all siblings. 


Related Information 
The CirculateNotify event. 


The XCirculateSubwindows subroutine, XCirculateSubwindowsDown subroutine, 
XCirculateSubwindowsUp subroutine. 
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XConfigureEvent Data Structure 


typedef struct { 


/* ConfigureNotify */ 


int type; 
unsigned long serial; /* Number of the last request 
processed by the server */ 
Bool send_event; /* True if this came from a 
SendEvent request */ 
Display *display; /* The display the event was read 


Window event 


from */ 


Window window; 


int x, y;3 


int width, height; 

int border_width; 

Window above; 

Bool override_redirect; 
} XConfigureEvent; 


The XConfigureEvent data structure includes the following fields: 


event 


window 


width 
height 
border_width 


above 


override_redirect 


Related Information 


Specifies the window on which the event was genereated. This field is 
set to either the reconfigured window or its parent, depending on 
whether StructureNotify or SubstructureNotify was selected. 


Specifies the window whose size, position, border, or stacking order 
was changed. 


Specifies the x coordinate of the upper left corner of the window. This 
coordinate is relative to the origin of the new parent window. 


Specifies the y coordinate of the upper left corner of the window. This 
coordinate is relative to the origin of the new parent window 


Specifies the size of the window, excluding the border. 
Specifies the size of the window, excluding the border. 
Specifies the width of the window border, in pixels. 


Specifies the window ID of the sibling window. This field is used for 
stacking operations. 


If the above field is set to the value of None, the reconfigured window 
is on the bottom of the stack with respect to sibling windows. 


If this field is set to a sibling window, the reconfigured window is placed 
on top of this sibling window. 


Specifies the value set in the override_redirect field of the window. If 
this field is the value of True, window manager clients should ignore 
the window. 


The ConfigureNotify event. 
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The XConfigureWindow subroutine, XLowerWindow subroutine, XRaiseWindow 
subroutine, XRestackWindows subroutine, XMoveWindow subroutine, XResizeWindow 
subroutine, XMoveResizeWindow subroutine, XMapRaised subroutine, 
XSetWindowBorderWidth subroutine. 


XCreateWindowEvent Data Structure 


The XCreateWindowEvent data structure includes the following fields: 


parent Specifies the parent of the created window. 
window Specifies the created window. 
x Specifies the x coordinate of the upper left outside corner of the 


created window. This coordinate is relative to the inside of the borders 
of the parent window. 


y | Specifies the y coordinate of the upper left outside corner of the 
created window. This coordinate is relative to the inside of the borders 
of the parent window. 


width Specifies the inside size of the created window, excluding the border. 
This field is always a nonzero value. 


height Specifies the inside size of the created window, excluding the border. 
This field is always a nonzero value. 


border_width Specifies the width of the border of the created window, in pixels. 


override_redirect | Specifies the value set in the override_redirect field of the window. If 
this field is set to the value of True, window manager clients should 
ignore the window. 


Related Information 
The CreateNotify event. 


The XCreateSimpleWindow subroutine, XCreateWindow subroutine. 


XDestroyWindowEvent Data Structure 


typedef struct { 


int type; /* DestroyNotify */ 

unsigned long serial; /* Number of the last request 
processed by the server */ 

Bool send_event; /* True if this came from a SendEvent 
request */ 

Display *display; /* The display the event was read 
from */ 


Window event; 
Window window; 
} XDestroyWindowEvent; 


The XDestroyWindowEvent data structure includes the following fields: 
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event 


window 


Related Information 


Specifies the window on which the event was generated. This field is set to 
either the destroyed window or its parent, depending on whether 
StructureNotify or SubstructureNotify was selected. 


Specifies the window that is destroyed. 


The DestroyNotify event. 


The XDestroySubwindows subroutine, XDestroyWindow subroutine. 


XGravityEvent Data Structure 


typedef struct { 


int type; /* GravityNotify */ 

unsigned long serial; /* Number of the last request 
processed by the server */ 

Bool send_event; /* True if this came from a 
SendEvent request */ 

Display *display; /* The display the event was read 
from */ 


Window event; 
Window window; 


int x, y; 


} XGravityEvent; 


The XGravityEvent data structure includes the following fields: 


event 


window 


x 


Related Information 


Specifies the window on which the event was generated. This field can be 
set to either the window that was moved or its parent, depending on 
whether StructureNotify or SubstructureNotify was selected. 


Specifies the window that was moved. 


Specifies the x coordinate of the upper left outside corner of the window. 
This coordinate is relative to the origin of the new parent window. 


Specifies the y coordinate of the upper left outside corner of the window. 


This coordinate is relative to the origin of the new parent window. 


The GravityNotify event. 


The XConfigureWindow subroutine, XMoveResizeWindow subroutine, XResizeWindow 


subroutine. 
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XMapEvent Data Structure 


typedef struct { 


int type; /* MapNotify*/ 

unsigned long serial; /* Number of the last request 
processed by the server */ 

Bool send_event; /* True if this came from a 
SendEvent request */ 

Display *display; /* The display the event was read 
from */ 


Window event; 

Window window; 

Bool override redirect; /* Boolean, is override set... */ 
} XMapEvent; 


The XMapEvent data structure includes the following fields: 


event Specifies the window on which the event was generated. This field 
is set to either the mapped window or its parent, depending on 
whether StructureNotify or SubstructureNotify was selected. 


window Specifies the window that was mapped. 


override_redirect Specifies the value set in the override_redirect field of the window. If 
this field is the value of True, window manager clients should ignore 
this window, because these events usually are generated from pop 
ups, which override structure control. 


Related Information 
The MapNotify event. 


The XMapRaised subroutine, XMapSubwindows subroutine, XMapWindow subroutine. 


XMappingEvent Data Structure 


typedef struct { 


int type; /* MappingNotify */ 

unsigned long serial; /* Number of the last request 
processed by the server */ 

Bool send event; /* True if this came from a SendEvent 
request */ 

Display *display; /* The display the event was read 
from */ 

Window window; /* Unused */ 

int request; /* MappingModifier, MappingKeyboard, 

MappingPointer */ 
int first_keycode; /* The first_keycode */ 
int count; /* Defines the range of change with 


first_keycode*/ 
} XMappingEvent; 


The XMappingEvent data structure includes the following fields: 
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request 


first_keycode 


count 


Specifies the kind of mapping change that occurred. The request 
field can have the following values: 


MappingModifier Indicates that the modifier mapping was 
changed. 

MappingKeyboard Indicates that the keyboard mapping was 
changed. 

MappingPointer Indicates that the pointer button mapping 


was changed. 


Specifies the first number in the range of the altered mapping. This 
field is set only if the request field is MappingKeyboard. 


Specifies the number of keycodes altered. This field is set only if the 
request field is MappingKeyboard. 


To update the client application’s knowledge of the keyboard, use the 
XRefreshKeyboardMapping subroutine. 


Related Information 


The MappingNotify event. 


The XChangeKeyboardMapping subroutine, XRefreshKeyboardMapping subroutine, 
XSetModifierMapping subroutine, XSetPointerMapping subroutine. 


XReparentEvent Data Structure 


typedef struct { 


int type; /* ReparentNotify */ 

unsigned long serial; /* Number of the last request 
processed by the server */ 

Bool send_event; /* True if this came from a 
SendEvent request*/ 

Display *display; /* The display the event was read 


Window event; 
Window window; 


Window parent; 
int x, y; 


from */ 


Bool override redirect; 


_} XReparentEvent; 


The XReparentEvent data structure includes the following fields: 


event 


window 


parent 


Specifies the window on which the event was generated. This field 
is set to either the reparented window or the old or new parent, 
depending on whether StructureNotify or SubstructureNotify was 
selected. 


Specifies the window that was reparented. 


Specifies the new parent window. 
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x . Specifies the x coordinate of the upper left outer corner of the 
reparented window. This coordinate is relative to the origin of the 
new parent window. 


y | Specifies the y coordinate of the upper left outer corner of the 
reparented window. This coordinate is relative to the origin of the 
new parent window 


override_redirect 


Specifies the value set in the override_redirect field of the 


reparented window. If this field is the value of True, window 
manager clients should ignore the window. 


Related Information 
The ReparentNotify event. 


‘The XReparentWindow subroutine. 


XUnmapEvent Data Structure 


typedef struct { 
int type; 
unsigned long serial; 


Bool sendevent; 
Display *display; 


Window event; 

Window window; 

Bool from_configure; 
} XUnmapEvent; 


/* UnmapNotify */ 

/* Number of the last request 
processed by the server */ 

/* True if this came from a 
SendEvent request */ 

/* The display the event was read 
from */ 


The XUnmapEvent data structure includes the following fields: 


event 


Specifies the window on which this event was generated. This 


paramer may be set to either the unmapped window or its parent, 
depending on whether StructureNotify or SubstructureNotify was 


selected. 


window 


from_configure 


Specifies the window that was unmapped. 


Specifies the value of True if the event was generated as a result of 


resizing the parent window when the window itself had a win_gravity 
field of UnmapGravity. 


Related Information 
ai ~ The UnmapNotify event. 


‘The XUnmapSubwindows subroutine, XUnmapWindow subroutine. 
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XVisibilityEvent Data Structure 


typedef struct { 


int type; /* VisibilityNotify */ 

unsigned long serial; /* Number of the last request 
processed by the server */ 

Bool send_event; /* True if this came from a 
SendEvent request */ 

Display *display; /* The display the event was read 
from */ 


Window window; 
int state; 
} XVisibilityEvent; 


The XVisibilityEvent data structure includes the following fields: 
window Specifies the window whose visibility state changes. 


state Specifies the visibility state of the window. This field can have one of the 
following values: 


VisibilityUnobscured 
VisibilityPartiallyObscured 
VisibilityFullyObscured. 


Related Information 
The VisibilityNotify event. 


XCirculateRequestEvent Data Structure 
typedef struct { 


int type; /* CirculateRequest */ 

unsigned long serial; /* Number of the last request 
processed by the server */ 

Bool send_event; /* True if this came froma 
SendEvent request */ 

Display *displav; /* The display the event was read 
from */ 


Window parent; 
Window window; 


int place; /* PlaceOnTop, PlaceOnBottom */ 
} XCirculateRequestEvent; 


The XCirculateRequestEvent data structure includes the following fields: 


parent Specifies the parent window. 
window Specifies the subwindow to be restacked. 
place Specifies the new position of the window in the stacking order. This 


field can have either of the following values: 


_ 5-118 AIX User Interface Programming Concepts 


PlaceOnTop Indicates that the window will be placed on top of 
all siblings. 


PlaceOnBottom Indicates that the window will be placed below all 
siblings. 
Related Information 
The CirculateRequest event. 


The XCirculateSubwindows subroutine, XCirculateSubwindowsDown subroutine, 
XCirculateSubwindowsUp subroutine. 


XConfigureRequestEvent Data Structure 


typedef struct { 


int type; /* ConfigureRequest */ 
unsigned long serial; /* Number of the last request 
processed by the server */ 
Bool send_event; /* True if this came from a 
. SendEvent request */ 
Display *display; /* The display the event was read 
from */ 


Window parent; 
Window window; 
int x, y; 
int width, height; 
int border width; 
Window above; 
int detail; /* Above, Below, TopIf, BottomIf, 
Opposite */ 
unsigned long value_mask; 
} xXConfigureRequestEvent; 


- The XConfigureRequestEvent data structure includes the following fields: 


parent Specifies the parent window. 
window Specifies the window to be reconfigured. 
x Specifies the x coordinate of the upper left outer corner of the 


reconfigured window. The value for this field is set according to the 
current geometry of the window. 


y Specifies the y coordinate of the upper left outer corner of the 
reconfigured window. The value for this field is set according to the 
current geometry of the window. 


width Specifies the size of the reconfigured window, excluding the border. The 
value for this field is set according to the current geometry of the window. 


height Specifies the size of the reconfigured window, excluding the border. The 
value for this field is set according to the current geometry of the window. 
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border_width Specifies the width of the border of the reconfigured window, in pixels. 
The value for this field is set according to the current geometry of the 


window. 

above Specifies the sibling window. This field can have one of the following 
values: 
None Indicates that the reconfigured window is placed 


on the bottom of the stack with respect to sibling 
windows. This is the default value for this field. 


SiblingWindow IDs The reconfigured window is placed on top of 
these sibling windows. 


detail Specifies the notify detail. This member can be set to Below, Toplf, 
Bottomlf, or Opposite. The default value for this field is Above. 

value_mask Specifies which components were indicated in the configure window 
request. 


Related Information 
The ConfigureRequest event. 


The XConfigureWindow subroutine, XLowerWindow subroutine, XMapRaised subroutine, 
XMoveResizeWindow subroutine, XMoveWindow subroutine, XRaiseWindow subroutine, 
XResizeWindow subroutine, XRestackWindows subroutine, XSetWindowBorderWidth 
subroutine. 


XMapRequestEvent Data Structure 


typedef struct { 





int type; /* MapRequest */ 

unsigned long serial; /* Number of the last request 
processed by the server */ 

Bool send_event; /* True if this came froma 
SendEvent request */ 

Display *display; /* The display the event was read 
from */ 


Window parent: 
Window window; 
} XMapRequestEvent; 


The XMapRequestEvent data structure includes the following fields: 
parent Specifies the parent window. 


window Specifies the window to be mapped. 


Related Information 
The MapRequest event. 


The XMapRaised subroutine, XMapSubwindows subroutine, XMapWindow subroutine. 


5~—120 AIX User Interface Programming Concepts 


XResizeRequestEvent Data Structure 


typedef struct { 


int type; /* ResizeRequest */ 

unsigned long serial; /* Number of the last request 
processed by the server */ 

Bool send_event; /* True if this came from a 
SendEvent request */ 

Display *display; /* The display the event was read 
from */ 


Window parent; 
int width, height; 
} XResizeRequestEvent; 


The XResizeRequestEvent data structure includes the following fields: 


window Specifies the window that another client attempted to resize. 
width Specifies the inside size of the window, excluding the border. 
height Specifies the inside size of the window, excluding the border. 


Related Information 
The ResizeRequest event. 


The XConfigureWindow subroutine, XMoveResizeWindow subroutine, XResizeWindow 
subroutine. 


XColormapEvent Data Structure 


typedef struct { 


int type; /* ColormapNotify */ 

unsigned long serial; /* Number of the last request 
processed by the server */ 

Bool send_event; /* True if this came from a 
SendEvent request */ 

Display *display; /* The display the event was read 
from */ 

Window window; 

Colormap colormap; /* The colormap or None */ 

Bool new; 

int state; /* ColormapInstalled, 


ColormapUninstalled*/ 
} XColormapEvent; 


The XColormapEvent data structure includes the following fields: 


window Specifies the window whose associated colormap is changed, installed, or 
uninstalled. 
colormap Specifies the colormap associated with the window for a colormap changed 


by a call to the XChangeWindowAttributes subroutine. For a colormap 
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changed by a call to the XFreeColormap subroutine, this field is the value 
of None. 


new Specifies if the colormap for the specified window was changed or installed 
or uninstalled. This field can have either of the following values: 


True Indicates that the colormap was changed. 
False Indicates that the colormap was installed or uninstalled. 


state Specifies if the colormap is installed or uninstalled. This field can have 
either of the following values: . 


Colormapinstalled 
ColormapUninstalled 
Related Information 
The ColormapNotify event. 


The XChangeWindowaAittributes subroutine, XFreeColormap subroutine, 
XInstallColormap subroutine, XSetWindowColormap subroutine, XUninstallColormap 
subroutine. 


XClientMessageEvent Data Structure 
typedef struct { 


int type; /* ClientMessage */ 

unsigned long serial; /* Number of the last request 
processed by the server */ 

Bool send_event; /* True if this came froma 
SendEvent request */ 

Display *display; /* The display the event was read 
from */ 


Window window; 

Atom message_type; 

int format; 

union { 
char b[20]; 
short s[10]; 
long ij5j; 
} data; 

} XClientMessageEvent; 


The XClientMessageEvent data structure includes the following fields: 
window Specifies the window to which the event was sent. 


message_type Specifies an atom which indicates how the data is to be interpreted by 
the receiving client. This field is not interpreted by the X Server. 


format Specifies whetner the data should be viewed as a list of bytes, shorts, 
or longs. This field should be set to 8 bits, 16 bits, or 32 bits. 


data Specifies a union which contains the members b (bytes), s (shorts), 
and | (longs). These members represent data of 20 8-bit values, 10 
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16-bit values, and 5 32-bit values. Some message types may not use 
ail these values. This field is not interpreted by the X Server. 


Related Information 
The XAnyEvent data structure. 


The ClientMessage event. 


The XSendEvent subroutine. 





XPropertyEvent Data Structure 


typedef struct { 
int type; /* 
unsigned long serial; /* 


Bool send_event; {x 
Display *display; /* 
Window window; 

Atom atom; 


Time time; 
int state; /* 


} XPropertyEvent; 


PropertyNotify */ 

Number of the last request 
processed by the server */ 
True if this came froma 
SendEvent request */ 

The display the event was 
read from */ 


PropertyNewValue, 
PropertyDeleted*/ 


The XPropertyEvent data structure includes the following fields: 


window Specifies the window whose associated property is changed. 
atom Specifies the atom of the property that is changed or requested. 
time Specifies the server time when the property is changed. 

state Specifies whether the property is changed to a new value or 


deleted. This field can have the following values: 


PropertyNewValue 


PropertyDeleted 


Related Information 
The PropertyNotify event. 


Indicates that the property is changed 
or that it is replaced with identical data 
using the XChangeProperty or 
XRotateWindowProperties 
subroutines. 


Indicates that the property is deleted 
using the XDeleteProperty or 
XGetWindowProperty subroutines. 


The XChangeProperty subroutine, XDeleteProperty subroutine, XGetWindowProperty 
subroutine, XRotateWindowProperties subroutine. 
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XSelectionClearEvent Data Structure 
typedef struct { 


int type; /* SelectionClear */ 

unsigned long serial; /* Number of the last request 
processed by the server */ 

Bool send_event; /* True if this came froma 
SendEvent request */ 

Display *display; | /* The display the event was read 
from */ 


Window window; 
Atom selection; 
Time time; 
} XSelectionClearEvent; 


The XSelectionClearEvent data structure includes the following fields: 


window Specifies the window losing ownership of the selection. 
selection Specifies the selection atom. 
time Specifies the last change time recorded for the selection. 


Related Information 
The SelectionClear event. 


The XSetSelectionOwner subroutine. 


XSelectionRequestEvent Data Structure 
typedef struct { 


int type; /* SelectionRequest */ 

unsigned long serial; /* Number of the last request 
processed by the server */ 

Bool send_event; /* True if this came from a 
SendEvent request */ 


Display *display; /* The display the event was read 
. from */ 
Window owner; 
Window requestor; 
Atom selection; 
Atom target; 
Atom property; 
Time time; 
} XSelectionRequestEvent; 


The XSelectionRequestEvent data structure includes the following fields: 


owner Specifies the window owning the selection. This is the window specified by 
the current owner in the XSetSelectionOwner subroutine. 


requestor Specifies the window requesting the selection. 
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selection 
target 
property 


time 


Related Information 


Specifies the atom that names the selection. 
Specifies the atom which indicates the type the selection is requested in. 
Specifies a property name or the value of None. 


Specifies the time, either in a timestamp (milliseconds) or in CurrentTime, 
taken from the XConvertSelection request. 


The SelectionRequest event. 


The XConvertSelection subroutine, XSetSelectionOwner subroutine. 





XSelectionEvent Data Structure 


typedef struct { 
int type; /* SelectionNotify */ 
unsigned long serial; /* Number of the last request 


processed by the server */ 


Bool send_event; /* True if this came from a 


SendEvent request */ 


Display *display; /* The display the event was 


read from */ 


Window requestor; 
Atom selection; 
Atom target; 
Atom property; /* The atom or None */ 
Time time; 
} XSelectionEvent; 


The XSelectionEvent data structure includes the following fields: 


requestor 
selection 
target 


property 


time 


Related Information 


Specifies the window associated with the requestor of the selection. 
Specifies the atom that indicates the selection. 
Specifies the atom that indicates the converted type. © 


Specifies the atom that indicates the property the result is stored on. This 
field is set to the value of None if the conversion fails. 


Specifies the time when the conversion took place. This can be a timestamp 
(in milliseconds) or CurrentTime. 


The SelectionNotify event. 


The XConvertSelection subroutine, XSendEvent subroutine. 
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XErrorEvent Data Structure 


typedef struct { 


int type; . 
Display *display; /* The display the event was 
. read from */ 

unsigned long serial; /* The serial number of the 
failed request */ 

unsigned char error_code; /* The error code of the failed 
request */ 

unsigned char request_code; /* The major op code of the 
failed request */ 

unsigned char minor_code; /* The minor op code of. the 


failed request */ 


XID resourceid; /* The resource id */ 


} XErrorEvent; 


The XErrorEvent data structure includes the following fields: 


display 


Serial 


error_code 


request_code 


minor_code 


resourceid 


Related Information 


Specifies the display that the event was read from. 


Specifies the number of requests, starting with the one sent over the 
network connection when it was opened. This value is the value of 
NextRequest immediately before the failing call was made. 


Specifies the error code of the failed request. 


Specifies a protocol request of the procedure that failed. The 
request_code field values are defined in the <X11/Xproto.hp> file. 


Specifies the minor op code of the failed request. 


Specifies the resource ID. 


The <X11/Xproto.h> header file. 


The XDisplayName subroutine, XGetErrorDatabaseText subroutine, XGetErrorText 
subroutine, XSetErrorHandler subroutine, XSetliOErrorHandler subroutine. 
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XWMhints Data Structure 


#define InputHint (1L<<0) 
#define StateHint (1L<<1) 
#define IconPixmapHint  #(1L<<2) 
#define IconWindowHint (1L<<3) 
#define IconPositionHint (1L<<4) 
#define IconMaskHint (1L<<5) 
#define WindowGroupHint (1L<<6) 
#define AllHints (InputHint/StateHint/IconPixmapHint/ 


IconWindowHint/IconPositionHint/ 
IconMaskHint/WindowGroupHint) 


typedef struct { 


long flags; /* Marks which fields in this 
structure are defined */ 
Bool input; /* Indicates whether this application 


relies on the window manager to get 
keyboard input */ 


int initial_state; /* The initial state of the 
application */ 
Pixmap icon_pixmap; /* The pixmap to be used as the icon */ 
Window icon_window; /* The window to be used as the icon */ 
int icon_x, icon_y; /* The initial position of the icon */ 
Pixmap icon_mask; /* The pixmap to be used as the mask 
for the icon_pixmap field */ 
XID window_group; /* The id of the related window 
group */ 
} XWMHints ; 


The XWMHints data structure includes the following fields: 


flags Specifies which fields are defined in the XWMHints data structure. 
The values for this field are as follows: 


InputHint 

StateHint 
IconPixmapHint 
IconWindowhint 
IconPositionHint 
IconMaskHint 
WindowGroupHint | 
AllHints 


input Specifies the input focus model used by the application. This field 
communicates the input focus model to the window manager and can 
have the following values: 
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True Indicates that the application accepts input, but 
never explicitly sets focus to any of the 
subwindows. These applications use the push 
model of focus management. The input field also 

_ has this value if the application sets input focus 
to its subwindows only when it is given to its top 
level window by a window manager. 


False indicates that the application manages its input 
focus by explicitly setting focus to one of its 
subwindows whenever keyboard input is 
requested. These applications use the pull model 
of focus management. The input field also has 
this value if the application never expects any 
keyboard input. 


Pull model window managers should make it possible for push model 
application to get input by setting input focus to the top level windows 
of applications with the input field set to the value of True. Push model 
window managers should ensure that pull model applications do not 
break them by resetting the input focus to PointerRoot when it is 


appropriate. 
initial_state Specifies the initial state of the application. The values for this field 
are: 
DontCareState Don’t know or care 
NormalState Most applications start this way 
ZoomState The application wants to start zoomed 
IconicState The application wants to start as an icon 
InactiveState The application believes it is seldom used; some 
window managers may put it on inactive menu 
icon_mask Specifies which pixels of the icon_pixmap field should be used as the 


icon. The icon_mask field allows for nonrectangular pixmaps. Both 
fields must be bit maps. 


icon_window Specifies the window to be used as an icon for window managers that 
support such use. 


window_group Specifies if this window belongs to a group of other windows. For 
example, if a single application manipulates multiple top level 
windows, this field provides the window manager with enough 
information to iconify all of the windows instead of only one window. 


Related Information 
The XGetWMHints subroutine, XSetWMHints subroutine. 
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XSizeHints Data Structure 


#define USPosition (1L<<0) /* user specified x, y */ 
#define USSize (1L<<1) /* user specified width, 
height */ 
#define PPosition (1L<<2) /* program specified position */ 
#define PSize (1L<<3) /* program specified size */ 
#define PMinSize (1L<<4) /* program specified minimum 
size */ 
#define PMaxSize (1L<<5) /* program specified maximum 
. size */ 
#define PResizeinc (1L<<6) /* program specified resize 
. increments */ 
#define PAspect (1L<<7) /* program specified min and 
max aspect ratios */ 
#define PAl1Hints (PPosition/PSize/PMinSize/ 


PMaxSize/PResizelInc/PAspect ) 


typedef struct { 
long flags; /* Marks which fields in this 
structure are defined */ 
int x, y; 
int width, height; 
int min_width, min_height; 
int max_width, max_height; 
int width_inc, height_inc; 


struct { 
int x; /* The numerator */ 
int y; /* The denominator */ 


} min_aspect, max_aspect; 
int base width, base_height; 
int win_gravity; 

} XSizeHints 


The XSizeHints data structure includes the following fields: 


flags Specifies how the position and size of the window is set. The values 
for this field are as follows: 


USPosition User specified x, y 

USSize User specified width, height 

PPosition Program specified position 

PSize Program specified size 

PMinSize Program specified minimum size 
PMaxSize Program specified maximum size 
PResizeinc Program specified resize increments 
PAspect Program specified minimum and maximum 


aspect ratios 
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PAIlHints (PPosition|PSize|PMinSize|PMaxSize|PResizeln 


c|PAspect) 
x Specifies the x coordinate for the upper left corner of the window. 
y Specifies the y coordinate for the upper left corner of the window. 
width Specifies the width of the window. 
height Specifies the height of the window. 
min_width Specifies the minimum width of the window for the application. 
min_height Specifies the minimum height of the window for the application. 
max_width Specifies the maximum width of the window. 
max_height Specifies the maximum height of the window. 
width_ine Specifies an atte progression of sizes, from minimum size to 


maximum size, for the window resize requests. 


height_inc Specifies an arithmetic progression of sizes, from minimum size to 
maximum size, for the window resize requests. 


min_aspect Specifies the minimum of the range of aspect ratios the application 
prefers. This field is expressed as a ratio of the x and y fields. 


max_aspect Specifies the maximum of the range of aspect ratios the application 
prefers. This field is expressed as a ratio of the x and y fields. 


base_width Defines an arithmetic progression, when used with the width_inc field, 
of the preferred window width. 


base_height Defines an arithmetic progression, when used with the height_inc field, 
of the preferred window height. 


Related Information 
The XGetNormalHints subroutine, XGetSizeHints subroutine, XGetZoomHints subroutine, 
XSetNormalHints subroutine, XSetSizeHints subroutine, XSetZoomHints subroutine. 


XlconSize Data Structure 


typedef struct { 
int min_width, min_height; 
int max_width, max_height; 
int width_inc, height_inc; 
} XIconSize; 


The XIconSize data structure includes the following fields: 


min_width Specifies the minimum icon width. 
min_height Specifies the minimum icon height. 
max_width Specifies the maximum icon width. 
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max_height Specifies the maximum icon height. 


width_inc Specifies an arithmetic progression of sizes, from minimum to 
maximum, that represent the supported icon sizes. 


height_inc Specifies an arithmetic progression of sizes, from minimum to 
maximum, that represent the supported icon sizes. 


Related Information 
The XGeticonSizes subroutine, XSeticonSizes subroutine. 





XClassHint Data Structure 


typedef struct { 
char *res_ name; 
char *res_ class; 
} XClassHint; 


The XClassHint data structure includes the following fields: 
res_name Specifies the application name. 


res_class Specifies the application class. 


Related Information 
The XGetClassHint subroutine, XSetClassHint subroutine. 


XrmValue Data Structure 


typedef struct { 
unsigned int size; 
caddr_t addr; 

} XrmValue, *XrmValuePtr; 


A resource database is an opaque type used by the lookup routines. 
typedef struct _XrmHashBucketRec *XrmDatabase; 


Database values consist of a size, an address, and a representation type. The 
representation type allows storage of data tagged by some application defined type (for 
example, font or color). It has nothing to do with the C language data type or with its class. 


The XrmValue data structure has the following fields: 
size Specifies the size of the resource database, specified in bytes. 


addr Specifies the location of the resource database. 
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XrmOptionDescList Data Structure 


typedef enum { 





XrmoptionNoArg, /* Value is specified in 
. OptionDescRec.value */ 
XrmoptionIsArg, /* Value is the option string 
itself */ 
XrmoptionStickyArg, /* Value is characters immediately 
following option */ 
XrmoptionSepArg, /* Value is next argument in argv */ 
XrmoptionResArg, /* Resource and value in next 
argument in argv */ 
XrmoptionSkipArg, /* Ignore this option and the next 
argument in argv */ 
XrmoptionSkipLine, /* Ignore this option and the rest 


of argv */ 
} XrmOptionKind; 


typedef struct { 


char *option; /* Option specification string in 
argv */ 

char *resourceName; /* Binding and resource name 
(sans application name) 

XrmOptionKind argKind; /* Which style of option it is */ 

caddr_t value; /* Value to provide if 


XrmoptionNoArg */ 
} XrmOptionDescRec, *XrmOptionDescList; 


The XrmOptionDescList data structure includes the following fields: 


option Specifies the option specification string in the argv field. 

resourceName Specifies the binding and resource name (without the application 
name). 

argKind Specifies the style of option. This field can be one of the following 
values: 
XrmoptionNoArg The value is specified in the value field. 
XrmoptionlsArg The value is the option string itself. 


XrmoptionStickyArg The value is found in the characters 
immediately following the option. 


XrmoptionSepArg The value is the next argument in the 
argv field. 
XrmoptionResArg The resource and value in the next 


argument in the argv field. 


XrmoptionSkipArg Ignore this option and the next argument 
in the argv field. 
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value 


Related Information 


XrmoptionSkipLine Ignore this option and the rest of the 


argv field. 


The value to provide if the argKind field is XrmoptionNoArg. 


The XrmParseCommand subroutine. 


XAIXDeviceMappingEvent Data Structure 


typedef struct { 
int type; 


unsigned long serial 


/* 


Event type */ 


/* Number of last request processed by 


server */ 


Bool send event; /* 
Display *display; /* 
Window window; /* 
int request; /* 
int lpfkmask; /* 


int lightmask; /* 


int dialmask; 


/* 


} XAIXDeviceMappingEvent; 


type 
serial 


send_event 


display 
window 
Ipfkmask 
lightmask 


dialmask 


True if from SendEvent request */ 
Display event was read from */ 
unused */ 

AIXMappingDial or AIXMappingLpfk */ 
lpfk input */ 

lpfk output */ 

dial mask */ 


Specifies the event type, which is AlXDeviceMappingNotify. 


Specifies the serial number of last event processed in the server. 


Specifies if the event was generated by a SendEvent protocol 
request. If it was, the send_event field is set to the value of True. 


Specifies the connection to the X Server. 


Unused in this request. 


Set to new Ipfkmask value if the request is AIXMappingLpfk. 


Set to the new lightmask value if the request is AIXMappingLpfk. 


Set to the new dialmask value if the request is AIXMappingDial. 
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Enhanced X-Windows Extensions Overview 


This chapter describes techniques for writing extensions to the Xlib library that have the 
same performance rate as Core protocol requests. The Using AIX Extensions section 
describes Enhanced X-Windows extensions. 


Note: Because an Enhanced X-Windows extension is expected to consist of multiple 
requests, defining 10 new features as 10 separate extensions is not a good practice. 
Rather, package new features into a single extension and use minor opcodes to 
distinguish between the features. 


Enhanced X-Windows Basic Extension Subroutines 
The basic protocol requests for extensions are the XQueryExtension extension subroutine, 
the XListExtensions extension subroutine, and the XFreeExtensionList extension 
subroutine. 


Hooking Into the Enhanced X-Windows Xlib Library 
Hooking routines sink a connecting hook into the library. These routines normally are not 
used by application programmers but, instead, by programmers who need to extend the 
Core Enhanced X-Windows protocol and the Enhanced X-Windows library interface. 
Hooking routines, which generate protoco! requests for Enhanced X-Windows, are called 
stubs. 


In extensions, stubs first check to see if they have initialized themselves on a connection. If 
the stubs have not been initialized, they should call the XInitExtension subroutine. 


The wire-formatted structure xEvent is in the <X11/Xproto.h> header file, and the 
host-formatted structure XEvent is in the <X11/Xlib.h> header file. 


The _XExtCodes data structure returns the information from the XQueryExtension 
extension subroutine. This structure is public to extension and cannot be changed. 


The XInitExtension subroutine calls the XQueryExtension subroutine to see if the 
extension exists. Then, it allocates storage for maintaining the information about the 
extension on the connection. It chains this to the extension list for the connection, and 
returns the information the stub implementor needs to access the extension. 


The extension number returned in the XExtCodes data structure is used in other calls. This 
extension number is unique to a single connection only. 
The types of functions and associated subroutines that hook into the Enhanced X-Windows 


lithea re mem She 


uorary aré tne following: 


e Creating a new graphics context for a connection (the ea a subroutine 
and the XESetCreateGC subroutine) 

e Copying a graphics context (the XESetCopyGC subroutine) 

e Freeing a graphics context (the XESetFreeGC subroutine) 

e Creating and freeing fonts (the XESetCreateFont subroutine and the XESetFreeFont 
subroutine) . 

e Converting events defined by extensions to and from wire format (the XESetWireToEvent 
subroutine and the XESetEventToWire subroutine) 

e Handling errors (the XESetError subroutine, the XESetErrorString subroutine, and the 
XGetErrorText subroutine). 


Use these routines to define procedures to be called under certain circumstances. All these 
routines return the previous routine defined for this extension. 
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Graphics Context (GC) Caching With Enhanced X-Windows | 
GC’s are cached by the library so that independent change requests can be merged into a 
single protocol! request. This cache is called a write back cache. Any extension subroutine 
whose behavior depends on the contents of a GC must flush the GC cache to make sure the 
server has up-to-date contents in its GC. 


If you extend the GC to add additional resource ID components, you should ensure that the 
library stub immediately sends the change request. Since a client can free a resource 
immediately after using it, storing the value in the cache without forcing a protocol request 
can destroy the resource before it is set into the GC. 


The _XFlushGCCache procedure forces the cache to be flushed. 


Using Enhanced X-Windows for Graphics Batching 
If you extend Enhanced X-Windows to add more poly-graphics primitives, you might be able 
to take advantage of facilities in the library to allow back-to-back single calls to be 
transformed into poly-requests. The display structure has a pointer to an xReq called 
last_req, which is the last request being processed. By checking that the last request type, 
drawable, GC, and other options are the same as the new one, and that there is enough 
space left in the buffer, you might be able to extend the previous graphics request by 
extending the length field of the request and appending the data to the buffer. — 


For example, here is the source for the XDrawPoint stub: 
#include <X11/Xlibint.h> 


/* precompute the max size of batching request allowed */ 


static int size = sizeof(xPolyPointReq) + EPERBATCH 
* sizeof(xPoint); 


XDrawPoint(dpy, d, gc, x, y) 
register Display *dpy; 
Drawable d; 

GC gc; 
int x, y; /* INT16 */ 


xPoint *point; 
LockDisplay(dpy); 
FlushGC(dpy, gc); 


{ 


register xPolyPointReq *req = (xPolyPointReq *) 
dpy—>last_req; 
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/* if same as previous request, with same drawable, 
batch requests */ 


if ( 
(req—>reqType == X_PolyPoint) 
&& (req~—>drawable == qd) 
&& (req—>gce == gc—>gid) 
&& (req—>coordMode == CoordModeOrigin) 
&& ((dpy—>bufptr + sizeof (xPoint)) <=dpy—>bufmax) 
&& (((char *)dpy—>bufptr — (char *)req) < size)) { 
point = (xPoint *) dpy—>bufptr; 
req—>length += sizeof (xPoint) >> 2; 
dpy—>bufptr += sizeof (xPoint); 


else { 

GetRegExtra(PolyPoint, 4, req ); /* 1 point = 4 bytes */ 

req—>drawable = d; 

req-—>gc = gc—>gid; 

req—>coordMode = CoordModeOrigin; 

point = (xPoint *) (req + 1); 

} 
point—>x 
point—>y 
} 
UnlockDisplay(dpy:); 
SyncHandle(); 


x; 
y; 


i 


To keep clients from generating long requests that might monopolize the server, there is a 
limit of EPERBATCH defined in <X11/Xlib.h> on the number of requests batched. Note that 
the FlushGC macro is called before picking up the value of the /ast_req field, since it may 
modify this field. 


Using Enhanced X-Windows to Define Extension Stubs, Requests and 


Replies 


The <X11/Xproto.h> header file contains three sets of definitions: 


e Request names 
e Request structures 
e Reply structures 


X Server requests contain the lengih, expressed in 16-bit quantity of 32-bits, of the request. 
Therefore, a single request can be no more than 256 kilobytes in length. Some servers may 
not support single requests of such a length. The value of display->max_request_size 
contains the maximum length as defined by the server implementation. 


An Xlib library stub routine should start as follows: 
#include <X11/Xlibint.h> 


XDoSomething (arguments, ...) /* argument declarations */ 


{ 


/* variable declarations, if any */ 


If the protocol request has a reply, then the variable declarations should include the reply 
structure for the request. The following is an example: 


xDoSomethingReply rep; 
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Generate a file equivalent to the <X11/Xproto.h> header file for your extension and include 
it in your stub routine. Each stub routine also must include the <X11/Xlibint.h> header file. 


The identifiers are deliberately chosen in such a way that if the request is called 
X_DoSomething, then its request structure is xDoSomethingReq and its reply is 
xDoSomethingReply. The GetReq family of macros, defined in the <X11/Xlibint.h> 
header file, takes advantage of this naming scheme. 


For each X Request, there is a definition in the <X11/Xproto.h> that looks similar to the 
following: 


#define X DoSomething 42 
In your extension header file, this is a minor opcode instead of a major opcode. 


Using Enhanced X-Windows to Define Request Formats 


Every request contains an 8-bit major opcode and a 16-bit length field expressed in units of 
4 bytes. Every request consists of a 4-byte header (containing the major opcode, the length 
field, and a data byte) followed by a 0 or additional bytes of data. The length field defines the 
total length of the request, including the header. The length field in a request must equal the 
minimum length required to contain the request. If the specified length is smaller or larger 
than the required length, the extension should generate a BadLength error. Unused bytes in 
a request are not required to be the value of 0. 


The XMaxRequestSize extension subroutine returns the maximum request size (4-byte 
units) supported by the server. 


Major opcodes 128 through 255 are reserved for extensions. Extensions are for holding 
multiple requests, therefore extension requests typically have an additional minor opcode 
encoded in the spare data byte in the request header. But the placement and interpretation 
of this minor opcode as weil as all other fields in extension requests are not defined by the 
Core protocol. Every request is implicitly assigned a sequence number (starting with one) 
used in replies, errors, and events. 


Most protocol requests have a corresponding structure typedef in the <X11/Xproto.h> 
header file. The following is an example of the xResourceReq typedef structure: 


typedef struct ResourceReq { 


CARD8 reqType; /* the request type, X_DoSomething */ 

BYTE pad; /* not used */ 

CARD16 length; /* 2 (= total number of bytes in 
request, divided by 4) * / 

CARD32 id; /* the window, drawable, font, or 
gcontext, for example * / 


} xResourceReq; 


reqlype Identifies the type of the request, such as the X_MapWindow value or the 
X_CreatePixmap value. 


length Identifies how long (in units of 4 bytes) the request is. It includes both the 
request structure and any variable length data, such as strings or lists, that 
follow the request struciure. Request structures come in different sizes, but 
all requests are padded to be a multiple of 4-bytes long. 


If a Core protocol request has a single 32-bit argument, you do not need to declare a 
request structure in your extension header file. Instead, such requests use the 
xResourceReq data structure in the <X11/Xproto.h>. This structure is used for any request 
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whose single argument is Window, Pixmap, Drawable, GContext, Font, Cursor, 
Colormap, Atom, or VisualiD. 


typedef struct DoSomethingReg { 


CARD8 reqType; /* X DoSomething * / 

CARD8 someDatum; /* used differently in different requests */ 
CARD16 length; /* total number of bytes in request, 

divided by 4 ; */ 

/* request-specific data */ 


} xDoSomethingReq; 


reqType Identifies the type of the request, such as the X_MapWindow value or the 
X_CreatePixmap value. 


length Identifies how long (in units of 4 bytes) the request is. It includes both the 
request structure and any variable length data, such as strings or lists, that 
follow the request structure. Request structures come in different sizes, but 
all requests are padded to be a multiple of 4-bytes long. 


You can do something similar in your extension header file. 


A few protocol requests take no arguments at all. Instead, they use the xReq data structure, 
which contains only a request type and a length (and a pad byte), in the <X11/Xproto.h> 
header file. 


Using Enhanced X-Windows to Define Reply Formats 
lf the protocol request requires a reply, then the <Xproto.h> header file also contains a reply 
structure typedef. 


typedef struct _DoSomethingReply { 


BYTE type; /* always X_Reply */ 
BYTE someDatum /* used differently in different 
requests */ 
CARD16 sequenceNumber; /* number of requests sent so far */ 
CARD32 length; /* number of additional bytes, 
divided by 4 * / 
/* request-specific data */ 


} xDoSomethingReply; 


Most of these reply structures are 32 bytes long. If the reply value is less than 32 bytes, the 
reply structure contains a sufficient number of pad fields to bring them up to 32 bytes. 


The length is the total number of bytes in the request minus 32, divided by 4. This field is not 
the value of 0 if: 


e The reply structure is followed by variable length data such as a list or string 
e The reply structure is longer than 32 bytes. 


The only extensions that have reply structures longer than 32 bytes are the following: 


The GetWindowAttributes protocol request 
The QueryFont protocol request 

The QueryKeymap protocol request 

The GetKeyboardControl protocol request. 
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A few protocol requests return replies that contain no data. The <X11/Xproto.h> header file 
does not define reply structures for these. Instead, these protocol requests use the 
xGenericReply structure, which contains only a type, length, and sequence number (and 
sufficient padding to make it 32-bytes long). 


Using Enhanced X-Windows to Lock Data Structures 
To support asynchronous input and multithreaded access to a single display connection, the 
display must be locked so that each stub can lock its critical section. Generally, this section 
is the point immediately prior to the appropriate GetReq call when all arguments to the call 
have been stored into the request. Two calls generally implemented as macros are: 
LockDisplay(disp/ay) 
Display “display, 


UnlockDisplay(disp/ay) 
Display “display; 


The display parameter specifies a pointer to the display structure of the display to be locked 
or unlocked. 


Using Enhanced X-Windows to Send Protocol Request and Arguments 
After the variable declarations, a stub routine should call one of four macros defined in the 
Xlibint.h file: 


The GetReq macro 

The GetReqExtra macro 
The GetResReq macro 
The GetEmptyReq macro 


These macros take the name of the protocol request as declared in the <X11/Xproto.h> 
header file without the X_, as their first argument. Each macro declares a Display structure 
pointer, called doy and a pointer to a request structure, called req, which is of the 
appropriate type. The macro then appends the request structure to the output buffer, fills in 
the type and length field, and sets the req variable to point to it. 


If the protocol request, such as GrabServer, has no arguments, use the GetEmptyReq 
protocol request as in the following example: 


GetEmptyReq (DoSomething); 


If the protocol request has a single 32-bit argument (such as a Pixmap, Window, 
Drawable, Atom), use the GetResRegq macro. 


The second argument to this macro is the 32-bit object. The X_MapWindow request type is 
a good example of the GetResReq macro: 


GetResReq (DoSomething, rid); 
The rid argument is the Pixmap or Window value, or other resource ID. 


If the protocol request takes any other argument list, then call the GetReq macro. After the 
GetReq macro, set all the other fields in the request structure, usually from arguments to the 
stub routine. 


GetReq (DoSomething); 
/* £i11 in arguments here */ 


req—>argl = argl; 
req—>arg2 = arg2; 
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A few stub routines, such as the XCreateGC subroutine and the XCreatePixmap 
subroutine, return a resource ID to the caller but pass a resource ID as an argument to the 
protocol request. These stub routines use the XAllocID macro to allocate a resource ID from 
the range of IDs that were assigned to this client when it opener the connection. The 
following is an example of the XAllocID macro: 


rid = req—>rid = XAllocID(); 
return (rid); 


Finally, some stub routines transmit a fixed amount of variable-length data after the request. 
Typically, these routines, such as the XMoveWindow subroutine and the XSetBackground 
subroutine, are special cases of more general routines like the XMoveResizeWindow 
subroutine and the XChangeGC subroutine. In these cases, the GetReqExtra macro, which 
is like the GetReq macro with an additional argument, is used. The additional argument is 
the number of extra bytes (a multiple of 4) allocated in the output buffer after the request 
structure. 


Using Variable Length Enhanced X-Windows Arguments 
Some protocol requests take additional variable length data that follow the 
xDoSomethingReq structure. The format of this data varies from one request to another. 
Some require a sequence of 8-bit bytes, others a sequence of 16-bit or 32-bit entities, and 
still others a sequence of structures. 


The length of any variable length data must be added to the length field of the request 
structure. The length field is in units of 32-bit longwords. If the data is a string or other 
sequence of 8-bit bytes, then round up the length and shift it before adding. For example: 


req—>length += (nbytes+3)>>2; 


To transmit the variable length data, use the Data macro. If the data fits into the output 
buffer, then this macro copies it to the buffer. If it does not fit, however, the Data macro calls 
the _XSend, which first transmits the contents of the buffer and then transmits your data. 
The Data macro takes three arguments: 


e the display 
e apointer to the beginning of the data 
e the number of bytes to be sent 


The following is an example of the Data macro: 

Data(display, (char *) data, nbytes); . 

If the data is 16-bit entities, her the PackData macro. It performs correctly on machines 
where a short is 22-bits instead of ine usuai 16. 


Both the Data and the PackData macros can use their last argument more than once, so 
that the argument field should be a variable rather than an expression, such as 
nitems*sizeof (item). This sort of computation should be done in a separate statement 
before calling the Data macro. 


lf the protocol request requires a reply, use the _XSend subroutine. The _XSend subroutine 
is faster than the Data macro, because it sends the data immediately instead of copying it 
into the output buffer. 


If the protocol request has a reply, use the _XReply extension subroutine after dealing with 
all the fixed and variable length arguments. 


Using Enhanced X-Windows For Synchronous Calling 
To ease debugging, each routine should have a call to a routine immediately prior to 
returning to the user. This routine is called SyncHandle() and is generally implemented as a 
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macro. If the synchronous mode is enabled, with the XSynchronize subroutine, the 
request is sent immediately. The library, however, waits until any error generated has been 
handled. 


Using Enhanced X-Windows to Allocate and Deallocate Memory 
To support the possible re-entry of these routines, several conventions should be observed 
when allocating and deallocating memory. This is appropriate especially when the user does 
not know the size of the data that is being returned. (The standard C language library 
routines on many systems are not protected against signals or other multithreaded use.) The 
analogies to standard 1/O library routines are defined as follows: 


Xmalloc() Replaces the malloc() routine 
Xfree() Replaces the free() routine 
Xcalloc() Replaces the calloc() routine. 


These routines should be used in place of any calls made to the normal C language library 
routines. For example, if you need a single scratch buffer inside a critical section to pack and 
unpack data to and from wire protocol, the general memory allocators may be too expensive 
to use (particularly in output routines, which are performance critical). Use the 
_XAllocScratch extension subroutine to return a scratch buffer. This storage must only be 
used inside the critical section of your stub. 


Using Enhanced X-Windows to Derive the Correct Extension Opcode 
When writing an extension stub routine map from the call to the proper major and minor 
opcodes. While there are a number of strategies, the simplest and fastest is outlined here: 


1. Declare an array of pointers. The length of this array, NFILE long (normally found in the 
<stdio.h> header file), is the number of file descriptors supported on the system of type 
XExtCodes. These descriptors should be initialized to the value of NULL. 


2. When your stub is entered, your initialization test should use the display pointer to access 
the file descriptor and an index into the array. If the entry is the value of NULL, then this 
is the first time you are entering the routine for this display. Call your initialization routine 
and pass the display pointer. 


3. Once in your initialization routine, call the XinitExtension subroutine. If it succeeds, 
store the pointer returned into this array. Establish a close display handler to allow you to 
zero the entry. Perform any other initialization your extension requires. (For example, 
install event handlers.) Your initialization routine normally will return a pointer to the 
XExtCodes data structure for this extension, which you would normally find in your array 
of pointers. 


4. After the initialization routine, the stub routine can continue normally, since its major 
opcode is safely in the XExtCodes data structure. 


Using Enhanced X-Windows Extension Event Types 
An extension event is data generated asynchronously by the X Server as a result of some 
input device activity or as side effects of an extension request. Device-related events 
propagate from the source window to ancestor windows until some client application has 
selected that event type or until the event is explicitly discarded. The X Server never sends 
an event to a client application unless the client has specifically asked to be informed of that 
event type, usually by calling the XSelectDevicelnput extension subroutine from the Xlib 
library. However, the AlXDeviceMappingNotify events are always sent. 
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The event type describes a specific event generated by the X Server. For each event type, a 
corresponding name is defined in the <X11/AIX.h> header file. The following table lists the 
event category and its associated event type or types. 


Event Category Event Type 

Lpfk events LPFKeyPress 

Dial events DialRotate 

Focus and mapping change events AlXFocusin 
AlXFocusOut 
AlXDeviceMappingNotify 


Using Enhanced X-Windows to Define Event Structures 
Each event type has a corresponding structure declared in the <X11/AIX.h> header file. 
Event structures have the following fields: 


type Specifies the event type constant name that uniquely identifies the type. For 
example, when the X Server reports a DialRotate event to a client 
application, it sends an XDialRotatedEvent structure with the type field set 
to DialRotate. 


displaylD Specifies a pointer to the display the event was read on. 
send_event Set to the value of True if the event came from an XSendEvent request. 


serial Set from the serial number reported in the protocol but expanded from the 
16-bit least-significant bits to a full 32-bit value. 


The X Server can send extension events at any time in the input stream, even while the 
client application sends a request and receives a reply. Events received, while waiting for a 
reply, can be stored by the Xlib library in the event queue. 


Using Enhanced X-Windows Event Masks 
Clients select extension event reporting of most events relative to a window by passing an 
extension event mask to an Xlib library event-handling function that takes the 
ext_event_mask argument. The bits of the event mask are defined in the <X11/AIX.h> 
header file. Each bit in the event mask maps to an event mask name. The event mask name 
describes the event or events to be returned to a client application by the server. 


The following table lists the event mask that can be specified in the ext_event_mask 
argument and the circumstances under which to specify them. 


Event Mask Circumstances 

NoEventMask No events wanted 
LPFKeyPressMask Lpfk key-down events wanted 
DialRotateMask Dial rotate events wanted 
DialRotateMask Dail rotate events wanted 
AlXFocusChangeMask Dial or Ipfk input focus events wanted 
AlXDeviceMapChangeMask Device state change events wanted. 


Using Enhanced X-Windows Dial and Lpfk Extensions 
The Ipfk and dial (or valuator) devices operate in two modes, AutoLoad and EventReport. 
These modes are mutually exclusive. The X Server automatically installs the attributes of 
dial and lpfk when in the AutoLoad mode. Under the EventReport mode, the client is 
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responsibie for downloading the attributes of dial and Ipfk into the X Server. The server starts 
up with the EventReport mode. 


Xlib provides routines to change the dial control or get the current dial control parameter. 
The dial control parameter is dial granularity. Routines for changing the on/off Ipfk keypress 
input and keylight output are also provided. 


The X Server can report LPFKeyPress events to a client when a Lighted Programmable 
Function Key (LPFKey) is pressed. To receive LPFKeyPress events in a client application, 
pass a window ID and the LPFKeyPressMask value as the EventMask parameter to 
XSelectLpfkinput. 


An LPFKeyPress event has an event type of LPFKeyPress and an associated structure 
name of XLPFKeyPressedEvent. 


The X Sever can report DialRotate events to a client when a dial is rotated. To receive 
DialRotate events in a client application, pass a window ID and DialRotateMask as the 
EventMask parameter to XSelectDialinput. 


DialRotate events are generated like KeyPress events. They have the DialRotate event 
type and an associated XDialRotatedEvent data structure. 


Processing Enhanced X-Windows Input Extension Events 


The event types reported to a client application during event processing depend on the event 
masks in the EventMask parameter of the XSelectDevicelnput extension subroutine. 
Processing descriptions include explanations of the structure or structures associated with 
the event. All the event structures contain type and display fields. 


The following table lists the event mask, the associated event type or types, and the 
structure name associated with the event type. 


[EventMask «(Event Type [siactwre 
LPFKeyPressMask LPFKeyPress XLPFKeyPressedEvent 
DialRotateMask XDialRotatedEvent 


AlXFocusChangeMask AiXFocusin AiXFocus!InEvent 
AlXFocusOut AlXFocusOutEvent 


AlXDeviceMapChangeMask A\XDeviceMappingNotify XAIXDeviceMappingFormat 







Processing Enhanced X-Windows Dial and Lpfk Events 


The X Server reports LPFKeyPress events to clients that need to know when an LPFKey is 
pressed. It also reports DialRotate events to clients that need to know when a dial is 
rotated. 


To receive LPFKeyPress events in a client application, pass a window ID and 
LPFKeyPressMask as the event_mask field to the XSelectLpfkinput extension subroutine. 
To select input for a specific key, use the XSelectLPFK subroutine. 


To receive DialRotate events in a client application, pass a window ID and DialRotateMask 
as the event_mask field to the XSelectDiallnput extension subroutine. To select the specific 
dial, use the XSelectDial subroutine. 


The source of the event is the smallest window containing the pointer. The window used by 
the X Server to report these events depends on its position in the window hierarchy and 
whether any intervening window prohibits the generation of these events. 


The X Server searches the window hierarchy, starting with the source window uniil it locates 
the first window specified by a client window specified by a client as having an interest in. 
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these events. If one of the intervening windows has its do_not_propogate_mask field set to 
prohibit generation of the event type, the event of those types are suppressed. Clients can 
modify the window used for reporting with the XSetDevicelnputFocus extension 
subroutine. 


The structures associated with these events are the XLFPKeyPressedEvent data structure 
and the XDialRotatedEvent data structure. These structures have the following fields: 


window Specifies the ID of the window on which the event was generated. It is 
referred to as the Event Window. The X Server uses this window to report 
the event. 

root Specifies the window ID of the source window or the root window. 

x_root Specifies the x coordinate, which is relative to the origin of the root window 


at the time of the event, and which is set to the pointer. 


y_root Specifies the y coordinate, which is relative to the origin of the root window 
at the time of the event, and which is set to the pointer. 


same_screen |ndicates whether the event window is on the same screen as the root 
window. This can be: 


True Indicates that the event window and the root window are on the same 
screen. 

False Indicates that the event window and the root window are not on the same 
screen. 


subwindow Specifies the child of the event window that is an ancestor of or is the 
source field if the source window is an inferior of the event window. 
Otherwise, the X Server sets subwindow to the value of None. 


time Specifies the time in milliseconds when the event was generated since the 
server reset. 


x Specifies the x coordinate, which is relative to the origin of the event window 
if the event window is on the same screen as the root window. Otherwise, 
this coordinate is the value of 0. 


y Specifies the x coordinate, which is relative to the origin of the event window 
if the event window is on the same screen as the root window. Otherwise, 
this coordinate is the value of 0. 


state Indicates the state of the pointer buttons and modifier keys just prior to the 
eveni. The pointer buttons can be the bitwise inclusive OR of one or more of 
the following button or modifier key masks: 


Button1 Mask Mod1Mask ShiftMask 
Button2Mask Mod2Mask LockMask 
Button3Mask Mod3Mask ControlMask 
Button4Mask Mod4Mask 
Button5Mask Mod5Mask 
The XLPFKeyPressedEvent data structure contains the following unique component: 
keycode Specifies a number that represents a physical key on the Ipfk that ranges 
from 0 to 31. 


The XDialRotatedEvent data structure contains the following unique components: 
diainum Specifies the dial that has been rotated. 
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dialval Specifies the difference between the current dial value and the last dial 
value. For clockwise rotation, this value is positive. For counterclockwise 
rotation, this value is negative. 


Processing Enhanced X-Windows Dial and Lpfk Input Focus Events 
This section describes the processing that occurs for the input focus events AlXFocusin 
and AlXFocusOut. The X Server reports AlXFocusin or AlXFocusOut events to clients 
requiring information about when the dial or Ipfk input focus changes. The dial or Ipfk is 
always attached to a window, which is usually the root window or a top-level window called 
the focus window. The focus window and the position of the pointer determines the window 
that receives dial of Ipfk input. 


To receive AlXFocusin and AlXFocusOut events in a client application, pass a window ID 
and AlXFocusChangeMask as the ext_event_mask field to XSelectDevicelnput. 


The fields of the AlXFocusinEvent data structure and the XAlXFocusOutEvent data 
structure associated with these events include the following: 


window Specifies the ID of the window on which the AlXFocusln or AlXFocusOut 
event was generated. The X Server uses this window to report the event 

mode Specifies the mode, which is NotifyNormal 

devitype Specifies the focus device 

detail Indicates the notify detail. It can be one of the following: 
NotifyAncestor NotifyVirtual 
Notifyinferior NotifyNonlinear 
NotifyNonlinearVirtual NotifyPointer 
NotifyPointerRoot NotifyDetailNone 


Processing Enhanced X-Windows AlXFocus Events 
Focus events are identified by the XAlXFocusInEvent data structure or the 
XAIXFocusOutEvent data structure whose mode field is NotifyNormal. The X Server 
processes normal focus events according to the following scenarios: 


1. When the focus moves from window A to window B and A is an inferior of B with the 
pointer in window P, the X Server generates the following: 


e An AlXFocusOut event on window A that has the XAlXFocusOutEvent data structure 
with NotifyAncestor as the detail field. 


e An AlXFocusOut event on each window between window A and window B exclusive 
that has the XAlXFocusOutEvent data structure with NotifyVirtual as the detail field. 


e An AlXFocuslin event on window B that has the XAlXFocusOutEvent data structure 
with Notifylnferior as the detail field. 


e An AlXFocusin event on each window below window B down to and including window 
P if window P is an inferior of window B, but is not window A, and is not an inferior of 
window A that has the XAIXFocusInEvent data structure with Notifyinferior as the 
detail field. 


2. When the focus moves from window A to window B and B is an inferior of A with the 
pointer in window P, the X Server generates: 


e An AlXFocusOut event on each window from window P up to, but not including 
window A (in that order), if window P is an inferior of window A, but is not window A, 
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and window P is not an inferior of window B nor an ancestor of window B that has the 
XAIXFocusOutEvent data structure with NotifyPointer as the detail field. 


An AlXFocusOut event on window A that has the XAlXFocusOutEvent data structure 
with Notifyinferior as the detail field. 


An AlXFocusin event on each window between window A and window B exclusive 
that has the XAlXFocusinEvent data structure with NotifyVirtual as the detail field. 


An AlXFocusin event on window B that has the XAlXFocusinEvent data structure 
with NotifyAncestor as the detail field. . 


3. When the focus moves from window A to window B and window C is their least common 
ancestor, and with the pointer in window P, the X Server generates the following: 


An AlXFocusOut event on each window from window P up to, but not including 
window A if window P is an inferior of window A that has the XAIXFocusOutEvent 
data structure with NotifyPointer as the detail field. 


An AlXFocusOut event on window A that has the XAIXFocusOutEvent data structure 
with NotifyNonlinear as the detail field. 


An AlXFocusOut event on each window between window A and window C exclusive 
that has the XAIXFocusOutEvent data structure with NotifyNonlinearVirtual as the 
detail field. 


An AlXFocusln event on each window between C and B exclusive that has the 
XAIXFocus!nEvent data structure with NotifyNonlinearVirtual as the detail field. 


An AlXFocusin event on window B that has the XAlXFocus!nEvent structure with 
NotifyNonlinear as the detail field. 


An AlXFocusin event on each window below window B down to and including window 
P and window P is an inferior of window B that has the XAIXFocusInEvent data 
structure with NotifyPointer as the detail field. 


4. If the focus window is PointerRoot (events sent to the window under the pointer) or 
None in XSetDevicelnputFocus, when the focus moves from window A to PointerRoot 
or None with the pointer in window P, the X Server generates the following: 


An AlXFocusOut event on each window from window P up to, but not including 
window A if window P is an inferior of window A that has the XAIXFocusOutEvent 
data structure with NotifyPointer as the detail field. 


An AiXFocusOut event on window A that has the XAIXFocusOutEvent data structure 
with Notifylnferior as the detail field. 


An AlXFocusOut event on each window above window A up to, and including its root 
window, and window A and is not a root window that has the XAlXFocusOutEvent 
data structure with NotifyNonlinearVirtual as the detail field. 


An AlXFocusin event on the root window of all screens that has the 
XAIXFocusInEvent data structure with NotifyPointerRoot or NotifyDetailINone as 
the detail field. 


An AlXFocusin event on each window from the root of window P down to, and 
including window P, (new focus PointerRoot) that has the XAlXFocus!inEvent data 
structure with NotifyPointerRoot as the detail field. 
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(5. When the focus moves from PointerRoot (events sent to the window under the pointer) 
or None to window A, with the pointer in window P, the X Server generates the following: 


An AlXFocusOut event on each window from window P up to and including the root of 
window P, (the old focus PointerRoot) that has the XAlXFocusOutEvent data 
structure with NotifyPointerRoot as the detail field. 


An AlXFocusOut event on all root windows that have the XAlXFocusEvent data 
structure with NotifyPointerRoot or NotifyDetailNone as the detail field. 


An AlXFocusin event on each window from the root of window A down to, but not 
including window A, and window A is not a root window, that has the 
XAIXFocusinEvent data structure with NotifyNonlinearVirtual as the detail field. 


An AlXFocusin event on window A that has the XAIXFocusInEvent data structure 
with NotifyNonlinear as the detail field. 


An AlXFocusin event on each window below window A down to, and including window 
P, and window P is an inferior of window A that has the XAIXFocusinEvent data 
structure with NotifyPointer as the detail field. 


6. When the focus moves from PointerRoot (events sent to the window under the pointer) 
to None (or vice versa), with the pointer in window P, the X Server generates the 
following: 


An AlXFocusOut event on each window from window P up to and including the root of 
window P, (the old focus PointerRoot) that has the XAlXFocusOutEvent data 
structure with NotifyPointerRoot as the detail field. 


An AlXFocusOut event on all root windows that have the XAIXFocusOutEvent data 
structure with NotifyPointerRoot or NotifyDetailNone as the detail field. 


An AlXFocusin event on all root windows that have the XAlXFocusinEvent data 
structure with NotifyDetailNone or NotifyPointerRoot as the detail field. 


An AlXFocusin event on each window below window P down to, and including window 
P (new focus is PointerRoot) that has the XAIXFocus!InEvent data structure with 
NotifyPointerRoot as the detail field. 


Processing Enhanced X-Windows AlXDeviceMappingNotify Events 
The X Server reports AlXDeviceMappingNotify events to all clients. This event type is 
generated when a client application uses the following: 


e The XSetDialContro! extension subroutine, which indicates that new dial granularity has 
been set. 


e The XSetLpfkControl extension subroutine, which indicates that new Ipfk input/output 
settings. 


The fields of the XAIXMappingEvent data structure associated with the 
XAIXDeviceMappingNotify event include request, dialmask, lpfkmask, and lightmask. 


e The request field indicates the kind of mapping change that occurred. It can be 
AlXMappingDial or AlXMappingLpfk. 


e Ifthe request field is AIXMappingDial, the dial granularity is changed. If the request field 
is AlXMappingLpfk, the Ipfk input/output setting is changed. 


The dialmask, Ipfkmask, and lightmask fields indicate the setting value. 
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Related Information 
The <X11/Xprote.h> header file. 


The _xDoSomethingReply data structure, xResourceReq data structure, 
xDoSomethingReq data structure , XExtCodes data structure. 


The _XAllocScratch extension subroutine, _XReply extension subroutine, 
XESetCloseDisplay extension subroutine, XESetCopyGC extension subroutine, 
XESetCreateFont extension subroutine, XESetCreateGC extension subroutine, 
XESetError extension subroutine, XESetErrorString extension subroutine, 
XESetEventToWire extension subroutine, XESetFlushGC extension subroutine, 
XESetFreeFont extension subroutine, XESetFreeGC extension subroutine, 
XESetWireToEvent extension subroutine, XFreeExtensionList extension subroutine, 
XGetErrorText subroutine, XInitExtension subroutine, XListExtensions extension 
subroutine, XMaxRequestSize extension subroutine, XQueryExtension extension 
subroutine, XSelectDevicelnput extension subroutine, XSelectDialinput extension 
subroutine, XSelectLpfkInput extension subroutine. 


The XCreateGC subroutine, XCreatePixmap subroutine, XMapWindow subroutine, 
XMoveWindow subroutine, XSynchronize subroutine. 


The GetKeyboardControl protocol request, GetWindowAtiributes protocol request, 
GrabServer protocol request, QueryFont protocol request, QueryKeymap protocol 
request. 


List of Enhanced X-Windows Extension Data Structures 
The _XExtCodes data structure 
The xDoSomethingReq data structure 
The xResourceReq data structure 
The XLPFKeyPressedEvent data structure 
The XDialRotatedEvent data structure 
The XAIXFocusChangeEvent data structure 


_XExtCodes Data Structure 


typedef struct _XExtCodes { 


int extension; /* extension number * / 
int major_opcode; /* major opcode assigned by server */ 
int first_event; /* first event number for the extension */ 
int first_error; /* first error number for the extension */ 


} XExtCodes; 
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XLPFKeyPressedEvent Data Structure 


typedef struct { 
int type; 
unsigned long serial; 


/* of event */ 

/* number of last request processed by 

the server */ 

/* true if this came from a SendEvent 

request */ 

/* display the ivent was read from */ 

/* "event" window it is reported 
relative to */ 

/* root window that the event occurred 


Bool send_event; 


Display *display; 
Window window; 


Window root; 


on */ 
Window subwindow; /* child window */ 
Time time; /* milliseconds */ 
int x, y; /* pointer x, y coordinates in the 
event window */ 
int x_root, y_ root; /* coordinates relative to root */ 
unsigned int state; /* key or button mask */ 
unsigned int keycode; /* detail */ 
Bool same_screen; /* same screen flag */ 


} XLPFKeyEvent; 


typedef XLPFKeyEvent XLPFKeyPressedEvent; 





XDialRotatedEvent Data Structure 


typedef struct { 
int type; 
unsigned long serial; 


/* of event */ 
/* number of last request processed by 
the server */ 


Bool send_event; 


Display *display; 
Window window; 


Window root; 


Window subwindow; 
Time time; 
ant. x; “y¥3 


int x_root, y_ root; 
unsigned int state; 
short int dialval; 
short int dialnum; 
Bool same_screen; 


/* true if this came from a SendEvent 

request */ 

/* display the ivent was read from */ 

/* "event" window it is reported 
relative to */ 

/* root window that the event occurred 

on */ 

/* child window */ 

/* milliseconds */ 

/* pointer x, y coordinates in the 
event window */ 

/* coordinates relative to root */ 

/* key or button mask */ 

/* dial value */ 

/* dial number */ 

/* same screen flag */ 


} XRotateEvent; 


typedef XRotateEvent XDialRotatedEvent; 
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XAIXFocusChangeEvent Data Structure 


typedef struct { 
int type; /* AIXFocusIn or AIXFocusOut */ 


unsigned long serial; /* number of last request processed 
by the server */ 

Bool send_event; /* true if this came from a SendEvent 
request */ 

Display *display; /* display the ivent was read from */ 

Window window; /* “event” window it is reported 
relative to */ 

short mode; /* NotifyNormal */ 

short devtype; /* dial or lpfk */ 

int detail; /* NotifyAncestor, NotifyVirtual, 


NotifyInferior, NotifyNonLinear, 
NotifyNonLinearVirtual, 
NotifyPointer, NotifyPointerRoot, 
NotifyDetailNone, */ 


} XAIXFocusChangeEvent; 


typedef XAIXFocusChangeEvent XAIXFocusInEvent; 
typedef XAIXFocusChangeEvent XAIXFocusOutEvent; 





Enhanced X-Windows Toolkit Overview 


The Enhanced X-Windows Toolkit provides basic subroutines for building a wide variety of 
application environments and gives programmers a common set of underlying user-interface 
subroutines. These tools simplify the design of application user interfaces in the Enhanced 
X-Windows programming environment. 





Enhanced X-Windows Intrinsics and Widgets Overview 


The Intrinsics library and a widget set make up the Enhanced X-Windows Toolkit. The 
Intrinsics provide the base mechanisms necessary to build a wide variety of widget sets and 
application environments. Because the Intrinsics mask implementation details from the 
widget and the annlication programmer, the widgets and the application environmenis buiit - 
with these widgets are fully extensible and support user-developed or extended components. 
By following a small set of conventions, widget programmers can extend their widget sets in 
new ways and can have these extensions function with the existing facilities. 


The Intrinsics library is a library package layered on the Xlib library. As such, the Intrinsics 
library provide subroutines and structures for extending the basic programming abstractions 
of the Enhanced X-Windows. By providing these subroutines and structures for 
intercomponent and intracomponent interactions, the Intrinsics library provide the next layer 
of functionality from which the widget sets are built. 


This X programming environment can be illustrated as three tiers, all sitting beneath the 
application program. The basic support (bottom tier) is the C language Enhanced 
X-Windows subroutines (Xlib). The Intrinsics is on the Xlib library. The widget set is on the 
Intrinsics. The combination of the Intrinsics and the widget set compose the Enhanced 
X-Windows Toolkit. 
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Application Program 


Widget Set 


Intrinsics 





The Enhanced X-Windows toolkit application is usually a client of a given widget set, a 
subset of the Intrinsics subroutines, and a smaller set of Xlib subroutines. At the same time, 
a widget set is a client of both the Intrinsics library and the Xlib library. And, the Intrinsics 
library is a client of the Xlib library only. 


For the application programmer, the Enhanced X-Windows Toolkit provides the following: 
e Aconsistent interface (widget set) for writing applications. 


e Aset of Intrinsics mechanisms (subroutines and structures) used also for writing 
applications. 


For the widget programmer, the Enhanced X-Windows Toolkit provides the following: 
e Asetof Intrinsics mechanisms for building widgets. 
e An architectural model for constructing and composing widgets. 


Applications that use the Enhanced X-Windows Toolkit must include the following header 
files: 


e <X11/Xlib.h> 

e <X11/Intrinsic.h> 

e <X11/StringDefs.h> 
and possibly <X11/Shell.h> 


Widget implementations should include the <X11/IntrinsicP.h> header file instead of the 
<X11/Intrinsic.h> header file. 


The applications should also include the additional headers for each widget class to be used, 
such as the <X11/Label.h> or <X11/Scroll.h> header file. The Intrinsics object library file is 
named the libXt.a file. 


Using Enhanced X-Windows to Define Widgets 
The fundamental data type of the Enhanced X-Windows Toolkit is the widget, a combination 
of a window and its associated semantics. A widget is dynamically allocated and contains 
. State information. Every widget belongs to one widget class that is allocated statically and 
initialized. The widget class contains the operations allowed on widgets of that class. 
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Logically, a widget is a rectangle with associated input and output semantics. Some widgets 
display information, such as text or graphics, while others are containers for other widgets, 
such as a menu box. Some widgets are output only and do not react to pointer or keyboard 
input, while others change their display in response to input and can call functions attached 
to them by an application. The user can alter much of the input and output of a widget, such 
as fonts, colors, sizes, and border widths. 


A wiaget instance is composed of two parts: 
e A data structure that contains instance-specific values. 
e Aclass structure that contains information that is applicable to all widgets of that class. 


Each widget class is logically composed of the procedures and data that is associated with 
all widgets belonging to that class. These procedures and data can be inherited by 
subclasses. 


Physically, a widget class is a pointer to a structure. The contents of this structure are 
constant for all widgets of the widget class, even though the values can vary from widget 
class to widget class. (Here, constant means the class structure is initialized at compile-time 
and never changed, except for a one-time class initialization and in-place compilation of 
resource lists. Compilation occurs when the first widget of the class or subclass is created.) 
A widget instance is allocated and initialized by the XtCreateWidget subroutine. 


The organization of the declarations and code for a new widget class between a public .h 
file, a private .h file, and the implementation .c file is described in Defining Widget Classes. 
The predefined widget classes adhere to the conventions found in Defining the Core Widget. 


There are three predefined widget classes: 


Core widget class | Defines the fields common to all widgets. All widget classes 
are subclasses of Core, which is defined by the 
CoreClassPart and CorePart structures. 


Composite widget class _—_ Exists as a subclass of the Core class and defines widgets 
that act as containers of other widgets. Composite widgets are 
defined by the CompositeClassPart and CompositePart 
structures. 


Constraint widget class Exists as a subclass of the Composite class and defines 
widgets that maintain additional state data for each child 
widget. This data can include client-defined contraints on the 

-child widget’s geometry. Constraint widgets are defined by the 
ConstraintClassPart and ConsirainiPart siruciures. 


Using Enhanced X-Windows to Name Widgets 
The Intrinsics library provide the ability to create new widgets and organize a set of widgets 
into an application. Use the following guidelines for naming new widgets: 


e A record component name is written in lowercase letters. If a name contains more than 
one word, the words are connected by _ (underscores). For example, the 
background_pixmap field is a compound record component name. 


e The first letter of procedure and type names is capitalized. Compound type and procedure 
names are capitalized at the beginning of each part of the name. For example, XtArgList 
is a compound procedure name and XtinputCallbackProc is a compound type name. 


e A resource name string is spelled the same as the record component name, except that 
capitalization is used for compound names. For the compiler to find spelling errors, each 
resource name should have a macro definition prefixed with XtN. For example, the 
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background_pixmap field has the corresponding resource name identifier 
XtNbackgroundPixmap, which is defined as the backgroundPixmap string. Since 
many predefined names are listed in the <X11/StringDefs.h> file, make sure any new 
name you Create is not in this file. 


e A resource class string starts with a capital letter and uses capitalization in compound 
names. For example, "BorderWidth” is a resource class compound name. Each resource 
class string should have a macro definition prefixed with XtC, for example, 
XtCBorderWidth. 


e A resource representation string is spelled the same as the type name, such as 
TranslationTable. Each representation string should have a macro definition prefixed 
with XtR, for example, XtRTranslationTable. 


e New widget class names begin with a capital letter. Capitalization is used to form 
compound words. For example, the following names can be derived from the AbeXyz 
new class name: 


Example Name of 

AbcXyzPart A partial widget instance structure. 
AbcXyzRec and _AbcXyzRec A complete widget instance structure. 
AbcXyzWidget A widget instance pointer type. 
AbcXyzClassPart A partial class structure. 


AbcXyzClassRec and_AbcXyzClassRec Acomplete class structure. 
abcXyzClassRec A class structure variable. 
abcXyzWidgetClass A class pointer variable. 


Action procedures available to translation specifications should follow the same naming 
conventions as procedures. Capitalize the first letter and use capitalization for compound 
names, for example, Highlight and NotifyClient. 


Using Enhanced X-Windows with the Core Widget Class 
The Core widget class defines the fields common to all widgets. All widget classes are 
subclasses of Core, which is defined by the CoreClassPart and CorePart data structures. 


All widget classes have the Core class fields as their first component. The prototypical type 
WidgetClass is defined with the Core class fields only. Various routines can cast widget 
class pointers, as needed, to specific widget class types. For example: 


typedef struct { 
CoreClassPart core class; 
} WidgetClassRec, *WidgetClass; 


The predefined class record and pointer for WidgetClassRec are the following: 
extern WidgetClassRec widgetClassRec, 


extern WidgetClass widgetClass; 


The opaque types, Widget and WidgetClass, and the opaque variable, widgetClass, are 
defined for generic actions on widgets. 
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All widget instances have the core fields as their first component. The prototypical type 
Widget is defined with the core set of fields only. Various routines can cast widget pointers, 
as needed, to specific widget types. For example: 


typedef struct { 
CorePart core; 
} WidgetRec, *Widget; 


Using Enhanced X-Windows with the Composite Widget Class 
The Composite widget class exists as a subclass of the Core class and defines widgets that 
act as containers of other widgets. Composite widgets are defined by the 
CompositeClassPart and CompositePart data structures. 


Composite widget classes have the composite fields immediately after the core fields: 


typedef struct { 
CoreClassPart core_class; 
CompositeClassPart composite_class; 

} CompositeClassRec, *CompositeWidgetClass; 


The predefined class record and pointer for CompositeClassRec are the following: 


extern CompositeClassRec compositeClassRec; 
extern WidgetClass compositeWidgetClass; 


The opaque types, CompositeWidget and CompositeWidgetClass, and the opaque 
variable, compositeWidgetClass, are defined for generic operations on widgets that are a 
subclass of CompositeWidget. 


Composite widgets have the following composite fields immediately after the core fields: 


typedef struct { 
CorePart core; 
CompositePart composite; 
} CompositeRec, *CompositeWidget; 


Using Enhanced X-Windows with the Constraint Widget Class 
The Constraint widget class exists as a subclass of the Composite class and defines widgets 
that maintain additional state data for each child widget. This data can include client-defined 
contraints on the geometry of the child widget. Constraint widgets are defined by the 
ConstraintClassPart and ConstraintPart structures. 


Constraint widget classes have the following constraint fields immediately after the 
composite fields: 


typedef struct { 
CoreClassPart core_class; 
CompositeClassPart composite_class; 
ConstraintClassPart constraint_class; 

} ConstraintClassRec, *ConstraintWidgetClass; 


The predefined class record and pointer for ConstraintClassRec are the following: 


extern ConstraintClassRec constraintClassRec, 
extern WidgetClass constraintWidgetClass; 


The opaque types ConstraintWidget and ConstraintWidgetClass, and the opaque 
variable, constraintWidgetClass, are defined for generic operations on widgets that area - 
subclass of ConstraintWidgetClass 


Constraint widgets have the following constraint fields immediately after the composite 
fields: 


5—154 AIX User Interface Programming Concepts 


typedef struct { 
CorePart core; 
CompositePart composite; 
ConstraintPart constraint; 

} ConstraintRec, *ConstraintWidget 


Related Information 
The <X11/Xlib.h> header file, <X11/Intrinsic.h> header file, <X11/IntrinsicP.h> header file, 
<X11/StringDefs.h> header file, <X11/Shell.h> header file. 


The CompositeClassPart data structure, CompositePart data structure, 
ConstraintClassPart data structure, ConstraintPart data structure, CoreClassPart data 
structure, CorePart data structure. 


Enhanced X-Windows Widget Classes Overview 


The widget_class field of a widget points to its widget class structure that contains 
information that is constant for all widgets of that class. 


With this class-oriented structure, widget classes do not usually implement procedures 
directly. Rather, widgets implement procedures available through their widget class 
structure. These class procedures are invoked by generic procedures that envelop common 
actions around the procedures implemented by the widget class. Such procedures are 
applicable to all widgets of that class and to widgets that are subclasses of that class. 


All widget classes are a subclass of the Core class and can be subclassed further. 
Subclassing reduces the amount of code and declarations you write to make a new widget 
class that is similar to an existing class. 


You do not have to describe every resource your widget uses in an XtResourceList data 
structure. Instead, describe the resources your widget has that its superclass does not. 
Subclasses usually inherit many of the procedures of their superclasses, such as the expose 
procedure or the geometry handler. On the other hand, subclassing too extensively creates a 
subclass that does not inherit the procedures of its superclass. 


To make good use of subclassing, widget declarations and naming conventions are highly 
stylized. A widget consists of three files: 


e A public .h file used by client widgets or applications. 
e A private .h file used by widgets that are subclasses of the widget. 


e A.c file.that implements the widget class. 


Using Enhanced X-Windows Widget Subclassing in Public .h Files 


The public .h file for a widget class is imported by clients. It contains the following: 


A reference to the public .h files for the superclass. 

The names and classes of the new resources to be added to its superclass. 
The class record pointer used to create widget instances. 

The C language type, which is used to declare widget instances of this class. 
Entry points for new class methods. 


The following example shows the public .h file for a possible implementation of the Label 
widget: 
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#ifndef LABEL_H 
#define LABEL _H 


/* New resources */ 


#define XtNjustify "justify” 
#define XtNforeground “foreground” 
#define XtNlabel "label” 
#define XtNfont "font” 


#define XtNinternalWidth “"internalWidth” 
#define XtNinternalHeight "internalHeight” 


/* Class record pointer */ 
extern WidgetClass labelWidgetClass; 


/* C widget type definition */ 
typedef struct LabelRec *LabelWidget; 


/* New class method entry points */ 
extern void Label SetText(); 

/* Widget widget */ 

/* String text */ 


extern String Label GetText(); 
/* Widget widget */ 


#endif LABEL_H 


Conditionally including the text allows the application to include header files for different 
widgets without determining if they have already been included as a superclass of another 
widget. 


To accommodate an operating system with file name length restrictions, the name of the 
public .h file is the first 10 characters of the widget class. For example, the public .h file for 
the Constraint widget is the Constraint.h file. 


Using Enhanced X-Windows Widget Subclassing in Private .h Files 
The private .h file for a widget is imported by widget classes that are subclasses of the 
widget. It contains: 


A reference to the public .h file for the class. 
A reference to the private .h file for the superclass. 
The new fields this widget adds to the widget siructure of iis superciass. 
The complete widget instance structure for this widget. 
The new fields added to the Constraint structure of its superclass if the widget is a 
subclass of Constraint. 
The complete Constraint structure if the widget is a subclass of Constraint. 
The new fields added to the widget class structure of its superclass. 
The complete widget class structure for this widget. 
The name of the constant for the generic widget class structure. 
. An inherit procedure for subclasses where each new procedure in the widget class 
structure should inherit a superclass operation. 
The following example shows the private .h file for the Label widget: 


#ifndef LABELP_H 
#define LABELP_H 


#include <X11/Label.h> 
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/* New fields for the 


typedef struct { 

/* Settable resources 
Pixel foreground; 
XFontStruct *font; 
String label; 
XtJustify justify; 
Dimension internal 


Dimension internal 
/* Data derived from 


GC normal_GC; 
GC gray GC; 


Label widget record */ 


ay 


/* text to display */ 
_width; /* # of pixels in horizontal 
border*/ 
_height; /* # of pixels in vertical border */ 


resources */ 


Pixmap gray_pixmap; 


Position label x; 
Position label y; 


Dimension label width; 
Dimension label _ height; 
Cardinal label len; 
Boolean display sensitive; 


} LabelPart; 


/* Full instance record declaration */ 
typedef struct _LabelRec { 


CorePart core; 
LabelPart label; 
} LabelRec; 


/* Types for label class methods */ 
typedef void (*LabelSetTextProc) (); 


/* Widget widget * 
/* String text */ 


/ 


typedef String (*LabelGetTextProc)(); 


/* Widget widget * 


; 


/* New fields for the Label widget class record */ 


typedef struct { 


LabelSetTextProc set_text; 
LabelGetTextProc get_text; 


_ caddr_t extension; 
} LabelClassPart; 


/* Full class record 


declaration */ 


typedef struct_LabelClassRec { 
CoreClassPart core _ class; 
LabelClassPart label _ class; 


} LabelClassRec; 


/* Class record variable */ 


extern LabelClassRec 


labelClassRec; 


#define LabelInheritSetText((LabelSetTextProc) XtInherit) 
#define LabelInheritGetText((LabelGetTextProc) XtInherit) 


#endif LABELP_H 


Chapter 5. Enhanced X-Windows 5—157 


To accommodate operating systems with file name length restrictions, the name of the 
private .h file is the first nine characters of the widget class followed by a capital P. 
For example, the private .h file for the Constraint widget is the ConstrainP.h file. 


Using Enhanced X-Windows Widget Subclassing in .c Files 
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The .c file for a widget contains the structure initializer for the class record variable. This 
initializer contains the following parts: 


e Class information, such as the following: 
— superclass, class_name, widget_size, class_initialize, class_inited. 
e Data constants, such as the following: 


— resources and num_resources, actions and num_actions, 
visible_interest, compress_motion, compress_exposure, version. 


e Widget operations, such as the following: 


- initialize, realize, destroy, resize, expose, set_values, accept_focus, 
and any operations specific to the widget. 


The superclass field points to the superclass WidgetClass record. For direct subclasses of 
the generic Core widget, superclass should be initialized to the address of the 
widgetClassRec structure. The superclass is used for class chaining operations and for 
inheriting or enveloping the operations of a superclass. Some of the fields are the following: 


class_name Specifies the text name for this class used by the resource manager. For 
example, the Label widget has the string "Label”. More than one widget 
class can use the same text class name. 


widget_size Specifies the size of the corresponding widget structure, not the size of the 
class structure. 


version Specifies the toolkit version number. This field is used at run time to check 
consistency of the Toolkit and widgets in an application. It should be set to 
the value returned by the XtVersion in the widget class initialization. 


To run widgets that are backwards compatible with previous Intrinsic versions, use the 
XtVersionDontCheck value. This value turns off version checking for those widgets. 


extension Used for upwards compatibility. If you add additional fields to class parts, all 
subclass structure layout change and complete recompilation is required. To 
avoid recompilation, an extension field at the end of each class part can 
poini to a record ihat contains any additional class information that is 
required. 


The following is a compressed version of the .c file for the Label widget. 


/* Resources specific to Label */ 


#define XtRJustify "Justify” 
static XtResource resources[{] = { 

{XtNforeground, XtCForeground, XtRPixel, sizeof(Pixel), 
XtOffset(LabelWidget, label.foreground), XtRString, 
XtDefaultForeground, 

{XtNfont, XtCFont, XtRFontStruct, sizeof(XFontStruct*), 
XtOffset(LabelWidget, label.font), XtRString, XtDefaultFont}, 

{XtNlabel, XtCLabel, XtRString, sizeof(String), 
XtOffset(LabelWidget, label.label), XtRString, NULL}, 
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} 


/* Forward declarations of procedures */ 


static 
static 
static 
static 
static 


void Initialize(); 
void Realize(); 
void SetText(); 
void GetText(); 


/* Class record constant */ 
LabelClassRec labelClassRec 
{ 
/* Core class fields */ 
/* superclass 
/* class_name 
/* widget_size 
/* class_initialize 
/* class_part_initialize 
/* class_inited 
/* initialize 
/* initialize hook . 
/* realize 
/* actions 
/* num_actions 
/* resources 
/* num_resources 
/* xrm_class 
/* compress_motion 
/* compress _exposure 
compress_enterleave 
visible interest 
destroy 
resize 
expose 
set_values 
set_values_hook 
set_values_almost 
get_values_hook 
accept_focus 
version 
callback_offsets 
tm_table . 
query geometry 
display accelerator 
extension 
}, 
{ 
/* Label class fields */ 
/* get_text 
/* set_text 
/* extension 
} 
}; 


/* Class record pointer */ 


void ClassInitialize(); 


*/ 


+) 
*/ 


(WidgetClass) &widgetClassRec, 
"Label”, 
sizeof(LabelRec), 
ClassInitialize, 
NULL, 

False, 

Initialize, 

NULL, 

Realize, 

NULL, 

0, 

resources, 
XtNumber(resources), 
NULLQUARK, 

True, 

True, 

True, 

False, 

NULL, 

Resize, 

Redisplay, 
SetValues, 

NULL, 
XtInheritSetValuesAlmost, 
NULL, 

NULL, 

XtVersion, 

NULL, 

NULL, 
XtInheritQueryGeometry, 
NULL, 

NULL, 


GetText, 
SetText, 
NULL, 
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WidgetClass labelWidgetClass = (WidgetClass) &labelClassRec; 


/* New method access routines */ 
void Label SetText (widget, text) 
Widget widget; 
String text; 


{ 
Label WidgetClass lwc = (Label WidgetClass) XtClass(widget); 
XtCheckSubclass(widget, labelWidgetClass, NULL); 
*(lwc—>label_class.set_text) (widget, text) 

} 


/*Private procedures*/ 


Using Enhanced X-Windows to Chain Superclass Operations 


Some fields defined in the widget class structure are self-contained and independent of the 
values for these fields defined in superclasses. Among these are the following: 


e class_name 

e accept_focus 

e class_initialize 

e compress_motion 
e widget_size 

e compress_exposure 
e realize 

e compress_enterleave 
e visible_interest 

e set_values_almost 
e resize 

e tm_table 

e expose 

e version. 


Some fields defined in the widget class structure are accessed only after their corresponding 
superclass value has been accessed. This is called downward superclass chaining. In this 
case, the invocation of a single operation first accesses the Core class, inen ihe subciass, 
and so on down the class chain to the widget class of the widget. These 
superclass-to-subclass fields are the following: 


class_part_initialize 
get_values_hook 
initialize_hook 
initialize 
set_values_hook 
set_values 
resources. 


In addition, for subclasses of the Constraint class, the resources field of the 
ConstraintClassPart structure is chained from the Constraint class down to the subclass. 


Some fields defined in the widget class structure are accessed before their corresponding 
superclass value has been accessed. This is called upward superclass chaining. In this 
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case, the invocation of a single operation actually first accesses the widget class, then its 
superclass, and so on up the class chain to the Core class. The subclass-to-superclass 
fields are the following: 


e destroy 
e actions. 


Using Enhanced X-Windows to Initialize a Widget Class 
Many class records can be initialized completely at compile time. In some cases, however, a 
class may need to register type converters or perform other kinds of 
“one-time” initializations. 


The C language does not have initialization procedures that are called automatically when a 
program starts up. Thus, a widget class can declare a class_initialize procedure that will be 
called (once) automatically by the X Toolkit. A class initialization procedure pointer is of the 
XtProc type. 


Specify the value of NULL in the class_initialize field to indicate that a widget class does not 
have a class initialization procedure. 


In addition to class initializations, some widget classes must must perform additional 
initializations for fields in their part of the class record. These initializations are performed in 
the class_part_initialize procedure, which is stored in the class_part_initialize field. The 
class_part_initialize procedure pointer is of the XtWidgetClassProc type. 


During class intialization, the class part initialization procedure for the class and its 
superciasses are called in superclass-to-subclass order on the class record. 


These procedures perform necessary dynamic initializations to the part of the record for their 
class. The most common procedure is the resolution of any inherited methods defined in the 
class. For example, if a widget class C has superclasses Core, Composite, A, and B, the 
class record for C is passed first to the class_part_initialize record of Core. This resolves any 
inherited Core methods and compiles the textual representations of the resource list and 
action table that are defined in the class record. Next, the Composite class_part_initialize 
procedure initializes the composite part of C’s class record. Finally, the class_part_initialize 
procedures for A, B, and C are called in order. 


Specify the value of NULL in the class_part_initialize field for classes that do not define new 
class fields or that do not need extra processing for their class fields. 


All widget classes must begin with the class_inited field set to the value of False, whether or 
not they have a class initialization procedure. 


The first time a widget of a class is created, the XtCreateWidget subroutine ensures that the 
widget class and all superclasses are initialized in superclass-to-subclass order by checking 
that each class_inited field is the value of False, by calling the class_initialize field and the 
class_part_initialize field procedures for the class and all its superclasses. 


Then, the Instrinsics library sets the class_inited field to the value of True. After the one-time 
initialization, a class structure is constant. 


The following is the class initialization procedure for the Label widget. 
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static void ClassInitialize() 


{ 
XtQEleft = XrmStringToQuark(”left”); 
XtQEcenter = XrmStringToQuark(”center”); 
XtQEright = XrmStringToQuark(”right”); 
XtAddConverter(XtRString, XtRJustify, CvtStringToJustify, 
NULL, 0); 
} 


A class is initialized the first time a widget of that class, or any subclass, is created. If the 
class initialization procedure registers type converters, these type converters are not 
available until the first widget is created. 


Using Enhanced X-Windows to Inherit Superclass Operations 
A widget class can use any of the self-contained operations of its superclass rather than 
implementing its own code. The inherited operations of the superclass most frequently used 
include the following: 


expose 

realize 

insert_child 
delete_child 
geometry_manager 
set_values_almost. 


To inherit an xyz operation, specify the XtIinheritXyz constant in your class record. Every 
class that declares a new procedure in its widget class part must provide for inheriting the 
procedure in its class_part_initialize procedure. 


The special chained operations initialize, set_values and destroy, which are declared in the 
Core record, do not have inherit procedures. Widget classes that do nothing beyond what 
their superclass does, specify the value of NULL for chained procedures in their class 
records. 


Inheriting compares the value of the field with a known, special value. If a match occurs, it 
copies the superclass value for that field. This special value is usually the Intrinsics library 
_XtInherit internal value cast to the appropriate type. (The _XtInherit internal value issues 
an error message if it is called directly.) 


For exampie, the Composite class private include file contains these definitions: 


#define XtInheritGeometryManager ((XtGeometryHandler) _XtInherit) 
#define XtInheritChangeManaged ((XtWidgetProc) _XtInherit) 
#define XtInheritInsertChild ((XtArgsProc) _XtInherit) 

#define XtInheritDeleteChild ((XtWidgetProc) _XtInherit) 


The Composite class_part_initialize procedure begins as follows: 


5-162 AIX User Interface Programming Concepts 


static void CompositeClassPartInitialize(widgetClass) 
WidgetClass widgetClass; 
{ 


register CompositeWidgetClass 
wc=(CompositeWidgetClass)widgetClass; 

CompositeWidgetClass 
super=(CompositeWidgetClass)wc—>core class.superclass; 


if (wc—>composite class.geometry manager == 
XtInheritGeometryManager) { 
wc—>composite _class.geometry manager = super—> 
composite _class.geometry manager; 


if (wc—>composite _class.change_ managed == 
XtInheritChangeManaged) { 
wc—>composite_class.change_ managed = super—> 
composite class.change_managed; 


The defined inherit constants for Core are the following: 


XtinheritRealize 
XtinheritResize 
XtinheritExpose 
XtInheritSetValuesAlmost 
XtinheritAcceptFocus 
XtinheritDisplay Accelerator. 


The defined inherit constants for Composite are the following: 


e XtinheritGeometryManager 
e XtinheritChangeManaged 
e XtlnheritinsertChild 

e XtinheritDeleteChild. 


Using Enhanced X-Windows to Call Superclass Operations 
A widget class sometimes needs to call a superclass operation that usually is not chained. 
For example, the expose procedure for a widget might call the expose procedure of its 
superclass and then perform more work of its own. Composite classes with fixed children 
can implement insert_child by calling their superclass insert_child procedure then, calling the 
XtManageChild subroutine to add the child to the managed list. 


The class procedure should call its own superclass procedure, not the superclass of the 
widget. The class procedure should use its own class pointers and not the class pointers of 
the widget. This technique is referred to as enveloping the operation of the superclass. 


Related information 
The XtResourceList data structure. 


The XtProc data type, XtWidgetClassProc data type. 
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The XtCheckSubclass macro, XtClass macro, XtSuperclass macro. 
The XtlsSubclass subroutine, XtManageChild subroutine. 


Enhanced X-Windows Widget Creation Overview 
The creation of widget instances is a three-phase process: 


1. The widgets are allocated and initialized with resources and are optionally added to the 
managed subset of their parent. 


2. All composite widgets are notified of their managed children in a bottom-up traversal of 
the widget tree. 


3. The widgets create windows that then get mapped. 


To start the first phase, the application calls the XtCreateWidget subroutine for all its 
widgets and adds them, as appropriate, to the managed set of their parent widget by calling 
the XtManageChild subroutine. To avoid an O(n**) creation process where each composite 
widget lays itself out each time a widget is created and managed, parent widgets are not 
notified of changes in their managed set during this phase. 


After all widgets have been created, the application calls the XtRealizeWidget subroutine on 
the top-level widget to start the second and third phases. The XtRealizeWidget subroutine 
first recursively traverses the widget tree in a post-order (bottom-up) traversal, and then 
notifies each composite widget that has one or more managed children through its 
change_managed procedure. 


Notifying a parent widget about its managed set involves geometry layout and, possibly, 
geometry negotiation. A parent widget must deal with constraints on its size that are 
imposed from above, as when a user specifies the application window size. A parent widget 
also deals with suggestions made from below, as when a primitive child widget computes its 
preferred size. Any clash between the two can cause geometry changes to ripple in both 
directions through the widget tree. The parent widget may force some of its children widgets 
to change size and position and may issue geometry requests to its own parent widget to 
accommodate all its children widgets better. Until this process is settled, placement on the 
screen is uncertain. 


Consequently, to avoid unnecessary requests to the X Server to move windows after 
creation, windows are not actually created in the first and second phases. 


Finally, the XtRealizeWidget subroutine starts the third phase by making a pre-order 
(top-down) traversal of the widaet tree, allocates an Enhanced X-Windows window to each 
widget by means of its realize procedure, and maps the managed widgets. 


Using Enhanced X-Windows to Create and Merge Argument Lists 
Many of the Intrinsics subroutines need to be passed pairs of resource names and values, 
called an argument list. These are passed as an ArgList structure, which contains the 
XtArgVal data structure. 


If the size of the resource is less than, or equal to, the size of an XtArgVal data structure, 
the resource value is stored directly in the Va/ue parameter. Otherwise, the Va/ue parameter 
is a pointer to the resource value. 


Using Enhanced X-Windows to Create a Widget Instance 
The XtCreateWidget subroutine creates an instance of a widget. This routine performs 
many of the boilerplate operations of widget creation. 
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Using Enhanced X-Windows to Create an Application Shell Instance 
Applications can have multiple top-level widgets, which can be on different screens. To 
create several independent windows, applications use the XtAppCreateShell subroutine, 
which creates a top-level widget that is the root of a widget tree. 


To create multiple top-level shells within a single logical application, use one of the following 
methods: 


e Designate one shell as the real top-level shell and create the others as pop-up children of 
the first with the XtCreatePopupShell subroutine. Use this method when you need to 
designate a main window. It leads to resource specifications as follows: 


xmail.geometry:... (main window) 
xmail.read.geometry:... (read window) 
xmail.compose.geometry.... (compose window). 


e Have all shells as pop-up children of an unrealized top-level shell. 
Use this method when you do not need to create a main window. It leads to resource 
specifications as follows: 


xmail.headers.geometry.... (headers window) 
xmail.read.geometry:... (read window) 
xmail.compose.geometry.... (compose window). 


Using Enhanced X-Windows to Initialize a Widget Instance 
The initialize procedure pointer in a widget class is of the XtlnitProc type. 


An initialization procedure performs the following: 


e Allocates space and copies any resources that are referenced by address. For example, if 
a widget has a field that is a String (char *), it cannot depend upon the characters at that 
address to remain constant, but must dynamically allocate space for the string and copy it 
to the new space. 


Note: Do not allocate space for or copy callback lists. 


e Computes values for unspecified resource fields. For example, if width and height are the 
value of 0, the widget computes a width and height based on other resources. This is the 
only time a widget can directly assign its own width and height. 


e Computes values for uninitialized non-resource fields that are 
derived from resource fields. For example, GCs that the 
widget uses are derived from resources like background, foreground, 
and font. 


An initialization procedure can also check certain fields for internal consistency, such as a 
specification of a color map for a depth that does not support that color map. 


Initialization procedures are called in superclass-to-subclass order. Most of the initialization 
code for a specific widget class deals with fields defined in that class and not with fields 
defined in its superclasses. 


If a subclass does not need an initialization procedure becauseit does not need to perform 
nay of the above operations, it can specify the value of NULL for the initialize field in the 
class record. 


Sometimes a subclass may want to overwrite values filled in by its superclass. In particular, 
size calculations of a superclass are often incorrect for a subclass. In this case, the subclass 
must modify or recalculate fields declared and computed by its superclass. For example, a 
subclass can visually surround its superclass display. In this case, the width and height 
calculated by the superclass initialize procedure are too small and need to be incremented 
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by the size of the surround. The subclass needs to know if its superclass size was calculated 
by the superclass or was specified explicitly. All widgets must place themselves into 
whatever size is explicitly given, but widgets should compute a reasonable size if no size is 
requested. 


In this example, the subclass with the visual surround can see if the width and height in the 
request widget are the value of 0. If so, the subclass adds its surround size to the width and 
height fields in the new widget. If not, the subclass must use the size originally specified. 


The new widget becomes the actual widget instance record. Therefore, if the initialization 
procedure needs to call any routines that operate on a widget, it should specify "new” as the 
widget instance. The request widget should never be modified. 


Using Enhanced X-Windows to Initialize a Constraint Widget Instance 
The constraint initialize procedure is of the XtInitProc type. The values passed to the parent 
constraint initialization procedure are the same values passed to the class widget 
initialization procedure of the child widget. 


The constraint initialize procedure should compute any constraint fields derived from 
constraint resources. It can make further changes to the widget to make the widget conform 
to the specified constraints, for example, changing the size or position of the widget. 


Specify the value of NULL for the initialize field of the ConstraintClassPart in the class 
record if a constraint class does not need a constraint initialization procedure. 


Using Enhanced X-Windows to Initialize Non-widget Data 
The value of the initialize_hook field allows a widget instance to initialize non-widget data 
using information from the specified argument list. For example, the Text widget has 
subparts that are not widgets, but these subparts have resources that can be specified by 
the resource file or an argument list. The initialize_hook field is of the XtArgsProc type. 


Using Enhanced X-Windows to Realize Widgets 
All the Instrinsics library routines and all widget routines should work with realized or 
unrealized widgets. To realize a widget instance, use the XtRealizeWidget subroutine. The 
widget procedure must create a window for the widget. In addition, some widget procedures, 
such as set_values, may choose to operate differently after the widget has been realized. 


The XtCreateWidget, XtRealizeWidget, XtManageChildren, XtUnmanageChildren, and 
XtDestroyWidget subroutines maintain the following invariants: 


e Ifa widget is realized, then all managed children of the widget are realized. 


e Ifa widget is realized, then all managed children of the widget that are 
mapped_when_managed are mapped. 


To determine whether a widget has been realized, use the XtlsRealized subroutine. 


Using Enhanced X-Windows to Create a Window for a Widget Instance 
A widget class can inherit its realize procedure from its superclass during class initialization. 
The realize procedure defined for the Core widget class calls the XtCreateWindow 
subroutine, with the passed va/ue_mask and attributes fields, and with the windowClass 
and the visual field set to CopyFromParent. Both CompositeWidgetClass and 
ConstraintWidgetClass inherit this realize procedure, and most new widget subclasses can 
do the same. 


The most common noninherited realize procedures set the bit_gravity field in the mask, set _ 
attributes to the appropriate value, and then create the window. For example, Label sets the 
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bit_gravity field to WestGravity, CenterGravity or EastGravity. Consequently, shrinking a 
Label moves the bits appropriately, and no Expose event is needed for repainting. 


If a composite widget wants to realize its children in a particular order, typically to control the 
stacking order, it calls the XtRealizeWidget subroutine on its children in the appropriate 
order from within its own realize procedure. 


Rather than call the XCreateWindow subroutine directly, a realize procedure should call the 
Toolkit analog XtCreateWindow. This routine, which simplifies the creation of windows for 
widgets, evaluates the following fields in the Core widget structure: 


°e x 
Lane 

e width 
e height 

e depth 

e screenparent —> core.window 


Widgets that have children but are not a subclass of the compositeWidgetClass are 
responsible for calling the XtRealizeWidget subroutine for their children, usually from within 
the realize procedure. 


Note: Because realize is not a chained operation, the widget classrealize procedure must 
update the XSetWindowAttributes data structure with all the appropriate fields from 
non-Core superclasses. 


Using Enhanced X-Windows to Obtain Window Information 
The Core widget definition contains the screen and window IDs. The window field can be the 
value of NULL for a while. 


The display pointer, the parent widget, the screen pointer, and the window of a widget are 
returned by the following macros, which take a widget and return the specified value: 


e The XtDisplay macro 
e The XtParent macro 

e The XtScreen macro 
e The XtWindow macro. 


Several window attributes are cached locally in the widget. Thus, the widgets can be set by 
the Resource Manager and the XtSetValues subroutine as well as the XtCreateWindow 
subroutine or subroutines that derive structures from these values. Examples of such 
structures are depth for deriving pixmaps and background _pixel for deriving GCs. 


The x, y, width, height, and border_width window attributes are available to geometry 
managers. These fields are maintained synchronously inside the Toolkit. When an 
XConfigureWindow subroutine is issued on the widget window at the request of the parent, 
these values are updated immediately rather than whenever the server generates a 
ConfigureNotify event. In fact, most widgets do not have SubstructureNotify turned on. 
This ensures that all geometry calculations are based on the internally consistent Toolkit, 
rather than on either: 


e inconsistencies updated by asynchronous ConfigureNotify events. 


e Wasteful consistencies, which slow the process because geometry managers ask the 
server for window sizes each time they need to layout their managed children widgets. 
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Using Enhanced X-Windows to Unrealize Widgets 
After widgets have been realized, they can also be unrealized. To destroy the windows 
associated with a widget and its descendants, use the XtUnrealizeWidget subroutine. 


Using Enhanced X-Windows to Destroy Widgets 


To destroy widgets, the Toolkit can: 


e Destroy all the pop-up children of the widget being destroyed and destroy all children of 
composite widgets. 


e Remove and unmap the widget from its parent. 

e Call the callback procedures that have been registered to trigger when the the widget is 
destroyed. 

e Minimize the number of things a widget has to deallocate when destroyed. 

e Minimize the number of XDestroyWindow calls. 


To destroy a widget instance, use the XtDestroyWidget subroutine. 


Using Enhanced X-Windows to Add and Delete Destroy Callbacks 
When an application needs to perform additional processing during the destruction of a 
widget, it should register a destroy callback procedure for the widget. The destroy callback 
list is identified by the XtNdestroyCaliback resource name. 


The following example calls the XtAddCallback subroutine to add to a widget the 
application-supplied destroy callback procedure, ClientDestroy, which has the 
client_data data. 


XtAddCallback (widget, XtNdestroyCallback, ClientDestroy, 
client_data) 


Similarly, the next example removes the application-supplied destroy callback procedure, 
ClientDestroy by calling the XtRemoveCallback subroutine. 


XtRemoveCallback (wadgets XtNdestroyCallback, ClientDestroy, 
client_data) 


The ClientDestroy procedure in both of the preceding examples is of the XtCallbackProc 


data type. 

Using Enhanced X-Windows to Deallocate Dynamic Constraint Data 
The destroy procedure pointer in the CoreClassPart data structure is ihe mh ViageiProc 
data type. 


The destroy procedure is called for a widget whose parent is a subclass of the 
constraintWidgetClass. The destroy procedures are called in subclass-to-superclass order, 
starting at the parent of the widget and ending at the constraintWidgetClass. Therefore, a 
constraint destroy procedure of a parent should deallocate only storage that is specific to the 
constraint subclass and not the storage allocated by any of its superclasses. Use the value 
of NULL for the constraint destroy procedure for the parent not requiring dealiocation of 
constraint storage. 


The destroy procedures are called in subclass-to-superclass order. Therefore, a destroy 
procedure for a widget should only deallocate storage specific to the subclass and not to its 
superclasses. It should deallocate only those resources that are explicitly created by the 
subclass. If a widget does not need to deallocate any storage, the destroy procedure in its 
widget class record can be the value of NULL.. 


Deallocating storage includes, but is not limited to, the following: 
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e Calling the XtFree subroutine on dynamic storage allocated with the XtMalloc, XtCalloc, 
and other subroutines. 


e Calling the XFreePixmap subroutine on pixmaps created with direct X calls. 


e Calling the XtDestroyGC subroutine on graphics contexts allocated with the XtGetGC 
subroutine. 


e Calling the XFreeGC subroutine on graphics contexts allocated with direct X calls. 


e Calling the XtRemoveEventHandler subroutine on event handlers added with the 
XtAddEventHandler subroutine. 


e Calling the XtRemoveTimeout subroutine on timers created with the 
XtAppAddTimeout subroutine. 


e Calling the XtDestroyWidget subroutine for each child if the widget has children widgets 
and is not a subclass of the compositeWidgetClass class. 


Using Enhanced X-Windows to Exit an Application 
Use the XtDestroyApplicationContext subroutine to end all toolkit applications. Then, exit 
normally. Or, use the XtUnmapWidget subroutine on each top-level shell widget. 


Using Enhanced X-Windows with Callbacks 
Applications and other widgets (clients) often want to register a procedure with a widget that 
is called under certain conditions. For example, when a widget is destroyed, every 
procedure in its destroy_callbacks filed is called to notify clients of its impending destruction. 


Every widget has a destroy_callbacks field. Additional callback lists can be defined as 
needed. For example, the Command widget has a callback list to notify clients when the 
button has been activated. Callback procedure fields for use in callback lists are of the 
XtCallbackProc type. 


To pass a callback list as an argument in a call to the XtCreateWidget, the XtSetValues, or 
the XtGetValues subroutines, a client specifies the address of a null-terminated list of the 
XtCallbackList data type. 


For example, the callback list for the A and B procedures with the clientDataA and 
clientDataB client data, respectively looks like the following: 


static XtCallbackRec callbacks[] = { 
{A, (caddr_t) clientDataA}, 
{B, (caddr_t) clientDataB}, 
{(XtCallbackProc) NULL, (caddr_t) NULL} 
}; 


Although callback lists are passed by address in argument lists, the Intrinsics library are 
aware of callback lists. The application-specific initialize and set_values procedures should 
not allocate memory for the callback list, as the Intrinsics library do this automatically by 
using a different structure for their internal representation. 


Whenever a widget contains a callback list for use by clients, it also exports in its public .h 
file the resource name of the callback list. Applications and client widgets never access 
callback list fields directly. Instead, they identify the desired callback list using the exported 
resource name. All callback manipulation routines check that the requested callback list is 
implemented by the widget. 


For the Intrinsics library to find and correctly handle callback lists, the lists should always be 
declared with the XtRCallback resource type. 


The following subroutines perform operations involving callback lists: 
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XtAddCallback Adds a callback procedure to a widget'’s callback list. 


XtAddCallbacks Adds a list of callback procedures to a widget’s callback list. 
XtRemoveCallback Deletes a callback procedure from a widget'’s callback list. 
XtRemoveCallbacks Deletes a list of callback procedures from a widget’s callback list. 


XtRemoveAllCallbacks Deletes all callback procedures from a widget'’s callback list. 
XtCallCallbacks Calls the procedures in a widget'’s callback list. 
XtHasCallbacks Determines the status of a widget’s callback list. 


Related Information 
The CoreClassPart data structure, XSetWindowaAttributes data structure, XtArgVal data 
structure, XtCallbackList data structure. 


The XtArgsProc data type, XtCallbackProc data type, XtinitProc data type, 
XtRealizeProc data type, XtWidgetProc data type. 


The XtDisplay macro, XtlsRealized macro XtParent macro, XtScreen macro, XtWindow 
macro. 


The XConfigureWindow subroutine, XFreeGC subroutine, XFreePixmap subroutine, 
XtAddCallback subroutine, XtAddCallbacks subroutine, XtAddEventHandler subroutine, 
XtAppAddTimeout subroutine, XtAppCreateShell subroutine, XtCallCallbacks 
subroutine, XtCalloc subroutine, XtCreatePopupShell subroutine, XtCreateWidget 
subroutine, XtCreateWindow subroutine, XtDestroyApplicationContext subroutine, 
XtDestroyGC subroutine, XtDestroyWidget subroutine, XDestroyWindow subroutine, 
XtFree subroutine, XtGetGC subroutine, XtGetSubresources subroutine, XtGetValues 
subroutine, XtHasCallbacks subroutine, XtMalloc subroutine, XtManageChild subroutine, 
XtManageChildren subroutine, XtMergeArgLists subroutine, XtRealizeWidget subroutine. 
XtRemoveAliCallbacks subroutine, XtRemoveCallback subroutine, XtRemoveCallbacks 
subroutine, XtRemoveEventHandler subroutine, XtRemoveTimeout subroutine, XtSetArg 
subroutine, XtSetValues subroutine, XtUnmanageChildren subroutine, Xt\UnmapWidget 
subroutine, XtUnrealizeWidget subroutine. 
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Enhanced X-Windows Widget Instantiation Overview 


A collection of widget instances constitutes a widget tree. The shell widget returned by the 
XtAppCreateShell subroutine is the root of the widget tree instance. The widgets with one 
or more children are the intermediate nodes of that tree, and the widgets with no children of 
any kind are the leaves of the widget tree. With the exception of pop-up children, this widget 
tree instance defines the associated Enhanced X-Windows tree. 


Widgets are either primitive or composite. Either kind can have children widgets. 


The Intrinsics library provides management mechanisms for constructing and interfacing 
between composite widgets, their children, and other clients. The Intrinsics library also 
recursively perform many operations, such as realization and destruction, on composite 
widgets and all of their children. 


While a composite widget can, in unusual circumstances, have no children, they usually 
have at least one. 


Pop-up children can be attached to any widget, regardless of class. Each pop-up child has a 
window that is a child of the root window so that the pop-up window is not clipped. 


Widgets with no children of any kind are leaves of a widget tree. Widgets with one or more 
children are intermediate nodes of a widget tree. The shell widget returned by the 
XtAppCreateShell subroutine is the root window of a widget tree. 


The normal children of the widget tree (including pop-ups) define the associated Enhanced 
X-Windows tree. 


A widget tree is manipulated by several Intrinsics subroutines: 


e The XtRealizeWidget subroutine, which traverses the tree downward and recursively 
realizes all pop-up widgets and children of composite widgets. 


e The XtDestroyWidget subroutine, which traverses the tree downward and destroys all 
pop-up widgets and children of composite widgets. 


e The XtMakeGeometryRequest subroutine, which traverses the tree one level upward 
and calls the geometry manager responsible for the child geometry of a widget. 


The subroutines that get and modify resources traverse the tree upward to determine the 
inheritance of resources from the ancestors of a widget. 


To facilitate up-traversal of the widget tree, each widget has a pointer to its parent widget. 
However, the XtAppCreateShell subroutine returns Shell widgets with a parent pointer of 
the value of NULL.. 


To facilitate down-traversal of the widget tree, each composite widget has a pointer to a list 
of children widgets. This list includes all normal children created, not just the subset of 
children that are managed by the composite geometry manager of the widget. In addition, 
every widget has a pointer to a list of pop-up children widgets. 


Using Enhanced X-Windows to Initialize Toolkit 
Before an application can call any of the Intrinsics subroutines, it must initialize the Toolkit by 
using the following: 


e The XtToolkitinitialize subroutine, which initializes the Toolkit internals. 


e The XtCreateApplicationContext subroutine, which initializes the per application state. 
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e The XtDisplayinitialize or XtOpenDisplay subroutine, which initialize the per cepey 
state. 


e The XtAppCreateShell subroutine, which creates the initial widget. 


Multiple instances of Toolkit applications can be implemented by a single program in a single 
address space. Each instance must be able to read input and dispatch events independently 
of any other instance. 


Applications may need multiple display connections or the same widgets on multiple 
screens. To achieve this, the Intrinsics library define application contexts, which provide the 
information necessary to distinguish one application instance from another. A list of Display 
pointers for that application is the major component of an application context. The 
XtAppContext application context type is opaque to clients. 


Using Enhanced X-Windows to Load Resource Database 
The XtDisplaytnitialize subroutine loads the application’s resource database for this 
display, host, and application combination. Each resource database is kept on a per-display 
basis, and is loaded from five sources, if they exist, in the following order: 


1. Application-specific class resource file on the local host. 

2. Application-specific user resource file on the local host. 

3. Resource property on the server or user preference resource file on the local host. 
4. Per-host user environment resource file on the local host. 

5. Application command line (argv). 


The application-specific resource file name is constructed from the class name of the 
application and points to a site-specific resource file that is installed by the site manager, 
usually when the application is installed. The application resource file is 
/usr/lpp/X11/appdefaults/class, where class is the application class name. This file should 
be provided by the application developer and may be required for the application to run 
properly. 


The application-specific user resource file name is constructed from the class name of the 
application and points to a user-specific resource file. This file is owned by the application 
and typically stores user customizations. This file name is constructed by using the value of 
the user's XAPPLRESDIR environment variable and appending class to it, where class is 
the application name. If this environment variable is not defined, the value defaults to the 
user’s home directory. If the resource file exists, it is merged into the resource database. The 
file may be provided with the anplication or constructed by the user. 


The server resource file is the contents of the X Server RESOURCE_MANAGER property 
as returned by the XOpenDisplay subroutine. The server resource file is constructed 
entirely by the user and contains both display-independent and display-specific user 
preferences. If the RESOURCE_MANAGER property does not exist, the resource file in the 
user’s home directory is used. This file is usually called the .Xdefaults file. If the resource 
file exists, it is merged into the resource database. 


The user’s environment resource file name is constructed by using the value of the user’s 
XENVIRONMENT variable for the full path of the file. If the user’s environment resource file 
exists, it is merged into the resource database. (This file name is user and host-specific.) 


If the XENVIRONMENT variable does not exist, the XtDisplayltnitialize subroutine searches 
the user’s home directory for the .Xdefaults-host file, wnere host is the name of the system 
where the application is running. lf this file exists, it is merged into the resource database. 
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The environment resource file should contain process-specific resource specifications 
intended to supplement the user-preference specifications in the server resource file. 


Use the XtDatabase subroutine to obtain the resource database for a particular display. This 
routine returns the fully merged resource database built by the XtDisplaylnitialize 
subroutine. 


Related Information 
The XtAppCreateShell subroutine, XtCloseDisplay subroutine, 
XtCreateApplicationContext subroutine, XtDatabase subroutine, 
XtDestroyApplicationContext subroutine, XtDestroyWidget subroutine, 
XtDisplaylnitialize subroutine, XtMakeGeometryRequest subroutine, XtRealizeWidget 
subroutine, XtWidgetToApplicationContext subroutine. 


Enhanced X-Windows Composite Widgets Overview 


Composite widgets are a subclass of the compositeWidgetClass. Composite widget 
functions are implemented directly by the widget class or indirectly by the Intrinsics 
subroutines. Composite widgets can have an arbitrary number of children widgets and 
consequently contro! more than primitive widgets. In general, composite widgets handle the 
following: 


e Overall management of child widgets from creation to destruction. 
e Destruction of descendants when the composite widget is destroyed. 


e Physical arrangement, or geometry management, of a displayable subset of managed 
children widgets. 


e Mapping and unmapping of a subset of the managed child widgets. 


Overall management is handled by the generic procedures of the XtCreateWidget and 
XtDestroyWidget subroutines. The XtCreateWidget subroutine adds child widgets to a 
parent widget by calling the insert_child procedure of the parent widget. The 
XtDestroyWidget subroutine removes child widgets from a parent widget by calling the 
delete_child procedure of the parent widget and also ensures that all children widgets of a 
destroyed composite widget get destroyed. 


Only a subset of the total number of child widgets is actually managed by the geometry 
manager and possibly visible. For example, a multibuffer composite editor widget can 
allocate one child widget for each file buffer while only displaying a small number of the 
existing buffers. Windows in this displayable subset are managed windows and enter into 
geometry manager calculations. The other children widgets are unmanaged windows and 
are not mapped. 


Child widgets are added to the managed set with the XtManageChild and 
XtManageChildren subroutines, and removed from the managed set by using the 
XtUnmanageChild and XtUnmanageChildren subroutines. These procedures notify the 
parent widget to recalculate the physical layout of its child widgets by calling the 
change_managed procedure of the parent widget. The XtCreateManagedWidget 
subroutine calls the XtCreateWidget and XtManageChild subroutines on the result. 


Most managed child widgets are mapped, but some widgets can be in a state where they 
take up physical space, but do not show anything. Managed widgets are not mapped 
automatically if the map_when_managed field is the value of False. The default for the 
map_when_managed field is the value of True. This field is changed by using the 
XtSetMappedWhenManaged subroutine. 
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Each composite widget class has a geometry manager responsible for calculating where the 
managed child widgets appear within the window of the composite widget. Geometry 
management techniques fall into the following four classes: 


Fixed boxes Have a fixed number of child widgets created by the parent. All of 
these children widgets are managed and none make geometry 
manager requests. 


Homogeneous boxes ___ Treat all child widgets equally and apply the same geometry 
; constraints to each child widget. Many clients insert and delete 
widgets freely. 


Heterogeneous boxes Place each child widget in a specific location. This location is not 
usually specified in pixels because the window can be resized, 
but is expressed in terms of the relationship between a child 
widget and the parent widget or between the child widget and 
other specific children widgets. Heterogeneous boxes are usually 
subclasses of Constraint. 


Sheil boxes Have only one child widget. This child widget is exactly the size 
of the shell. The geometry manager must communicate with the 
window manager if it exists. The box must also accept the 
ConfigureNotify events when the window size is changed by the 
window manager. . 


Using Enhanced X-Windows to Verify the Class of a Composite Widget 
To determine if a given widget is a subclass of the Composite widget, use the 
XtlsComposite subroutine. This subroutine is equivalent to the XtlsSubclass subroutine 
with the compositeWidgetClass field specified. 


Using Enhanced X-Windows to Add Children to a Composite Widget 
To add a child widget to the list of children widgets of a parent widget, the XtCreateWidget 
subroutine calls the insert_child class routine of the parent widget. The insert_child 
procedure pointer in a composite widget is of the XtWidgetProc type. 


Most composite widgets inherit the operation of their superclass. The /nsert_child routine of 
the composite widget calls the insert_position procedure and inserts the child widget at the 
specified location. 


Some composite widgets define their own insert_child routine so that they can order their 
child widgets in some convenient way, create companion controller widgets for a new widget, 
or limit the number or type of their child widgets. 


lf there is not enough room to insert a new child widget in the child widget list (if 
num_children = num_slots), the insert_child procedure must first reallocate the list and 
update the num_siots field. The insert_child procedure calculates a location for the child 
widget, inserts the child in the location, and increments the num_children field. 


Using Enhanced X-Windows to Insert Children in a Specific Order 
Instances of composite widgets must specify the order in which their child widgets are kept. 
For example, an application may require a set of command buttons in some logical order 
grouped by function or buttons representing file names in alphabetical order. 


The insert_position procedure pointer in a composite widget instance is of the XtOrderProc 
type. 
Composite widgets that allow clients to order their child widgets are usually homogeneous 


boxes. These widgets call the insert_position procedure of the widget instance from the 
insert_child procedure of the class to determine where a new child widget is placed in the 
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child widget array of the composite widget. A client of a composite class can apply different 
sorting criteria to widget instances of the class, passing in a different insert_position 
procedure when it creates each composite widget instance. 


The return value of the insert_position procedure indicates how many children widgets go 
before the widget. 


e When a value of 0 is returned, the widget goes before all other children widgets. 


e When the num_children field is returned, the widget goes after all other children widgets. 
The insert_position default returns the num_children field. This default can be overridden 
by the resource list of a widget or by the argument list provided when the composite 
widget is created. 


Using Enhanced X-Windows to Delete Children of Composite Widgets 
To remove a child widget from the child widget array of a parent widget, the 
XtDestroyWidget subroutine calls the delete_child procedure of the composite parent 
widget. The delete_child procedure pointer is of the XtWidgetProc type. 


Most widgets inherit the delete_child procedure from their superclass. Composite widgets 
that create companion widgets define a delete_child procedure to remove these companion 
widgets. 


Using Enhanced X-Windows to Manage Children in a Managed Set 
The Intrinsics library provide a set of generic subroutines for adding widgets to the managed 
set of a composite widget and removing widgets from the managed set of a composite 
widget. These generic subroutines call the change_managed procedure of the widget. The 
change_managed procedure pointer is of the XtWidgetProc type. 


Using Enhanced X-Windows to Add Children to a Managed Set 
To add a list of widgets to the geometry-managed displayable subset of its composite parent 
widget, the application must first create the widgets using the XtCreateWidget subroutine 
and then call the XtManageChildren subroutine. 


Managing child widgets is independent of ordering, creating, and deleting child widgets. The 
layout routine of the parent widget considers child widgets with a managed field equal to the 
value of True and ignores all other child widgets. Some composite widgets, especially fixed 
boxes, call the XtManageChild subroutine from their insert_child procedure. 


If the parent widget is realized, the change_managed procedure of the parent widget 
confirms that its set of managed child widgets has changed. The parent widget can 
reposition and resize any of its child widgets. The position of a child widget is changed by a 
call to the XtMoveWidget subroutine. This subroutine updates the x and y fields and calls 
the XMoveWindow subroutine if the widget is realized. 


To change the size or border width of any of its child widgets, a composite widget calls the 
XtResizeWidget subroutine. This procedure first updates the Core fields, and then calls the 
XConfigureWindow subroutine if the widget is realized. 


To add a single child widget to the list of managed child widgets of a parent widget, first 
create the child widget with the XtCreateWidget subroutine, and then use the 
XtManageChild subroutine. The XtManageChild subroutine constructs a WidgetList of 
length one and calls the XtManageChildren subroutine. 


To create and manage a child widget in a single procedure, use the 
XtCreateManagedWidget subroutine. This subroutine calls the XtCreateWidget and 
XtManageChild subroutines. 
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ne Enhanced X-Windows to Remove Children from a Managed Set 
To remove child widgets from the managed list of a parent widget, use the 
XtUnmanageChildren subroutine. The specified widgets are not destroyed by this 
subroutine and can be added to the managed list again at a later time. 


To remove a single child widget from the managed set of a parent widget, use the 
XtUnmanageChild subroutine. The XtUnmanageChild subroutine constructs a widget list 
of length one and calls the XtUnmanageChildren subroutine. 


These generic functions are low-level subroutines used by generic composite widget building 
subroutines. Composite widgets also can provide widget-specific high-level procedures for 
the creation and management of child widgets. 


Using Enhanced X-Windows to Determine if a Widget is Managed 
To determine the managed state of a given child widget, use the XtIlsManaged macro. The 
XtlsManaged macro is implemented as a boolean macro and as a function. Both forms 
return the value of True if the specified child widget is managed and the value of False if the 
child widget is not managed. 


Using Enhanced X-Windows to Control Widget Mapping 
A managed widget is usually mapped. The mapping can be overridden by setting the 
XtNmappedWhenManaged resource for the widget when it is created or by setting the 
map_when_managed field to the value of False. 


To change the value of the map_when_managed field of a widget, use the 
XtSetMappedWhenManaged subroutine. The XtSetMappedWhenManaged subroutine is 
equivalent to calling the XtSetValues subroutine and setting the new value for the 
mappedWhenManaged resource. 


An alternative to using the XtSetMappedWhenManaged subroutine to control mapping is 
having the client set the mapped_when_managed field to the value of False and calling the 
XtMapWidget and XtUnmapWidget subroutines explicitly to map and unmap a widget. 


Using Enhanced X-Windows with Constrained Composite Widgets 
Constraint widgets are a subclass of the compositeWidgetClass. Constraint widgets 
manage the geometry of their child widgets based on constraints associated with each child 
widget. Constraints can be simple, such as the maximum width and height that the parent 
widget allows the child to occupy, or complex, such as instructions on how other child 
widgets should change if this child widget is moved or resized. 


Constraint widgets let a parent widget define resources supplied for its child widgets. For 
example, if a constraint parent widget defines the maximum sizes for its child widgets, these 
new size resources are retrieved for each child widget as if they were resources defined by 
the child widget. Constraint resources can be included in an argument list or resource file 


just like any other resource for the child widget. 


Constraint widgets have all the functionality of standard composite widgets. These widgets 
also process and act upon the constraint information associated with each of their child 
widgets. 


Every widget has a constraints field. This field enables widgets and the Intrinsics library to 
keep track of the constraints associated with a child widget. The field contains the address of 
a parent-specific structure that contains constraint information about the child widget. If the 
parent widget is not a subclass of the constraintWidgetClass, the constraints field of the 
child widget is the value of NULL. . 


Subclasses of a Constraint widget can add more constraint fields to their superclass. To add 
more constraint fields, you define the constraint records in a private .h file using the same 
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conventions as for widget records. For example, a widget that needs to maintain a maximum 
width and height for each child widget might define its constraint record as the following: 


typedef struct { 
Dimension max_width, max_height; 
} MaxConstraintPart; 


typedef struct { 
MaxConstraintPart max; 
} MaxConstraintRecord, *MaxConstraint; 


A subclass of this widget that needs to maintain a minimum size can define its constraint 
record as the following: 


typedef struct { 
Dimension min_width, min_height; 
} MinConstraintPart; 


typedef struct { 
MaxConstraintPart max; 
MinConstraintPart min; 
} MaxMinConstraintRecord, *MaxMinConstraint; 


Constraints are allocated, initialized, deallocated, and maintained by the Intrinsics library. 
The constraint class record part has several entries that facilitate this control. All entries in 
the ConstraintClassPart resource are information and procedures defined and 
implemented by the parent widget and called whenever actions are performed on the child 
widgets of the parent widget. 


The XtCreateWidget subroutine uses the constraint_size field to allocate a constraint record 
when a child widget is created. This field specifies the number of bytes occupied by a 
constraint record. The XtCreateWidget subroutine also uses the constraint resources to fill 
in resource fields in the constraint record associated with a child widget. It then calls the 
constraint initialize procedure so the parent widget can compute constraint fields derived 
from constraint resources and moves or resizes the child widget to conform to the given 
constraints. 


The XtGetValues and XtSetValues subroutines use the constraint resources to get or set 
the values of constraints associated with a child widget. The XtSetValues subroutine then 
calls the constraint set_values procedures so the parent widget can recompute derived 
constraint fields and move or resize the child widget as appropriate. 


. The XtDestroyWidget subroutine calls the constraint destroy procedure to deallocate 
dynamic storage associated with a constraint record. The constraint record must not be 
deallocated by the constraint destroy procedure, as the XtDestroyWidget subroutine 

- deallocates the constraint record automatically. 


Related Information 
. The XtOrderProc data type, XtWidgetProc data type. 


The XtisComposite macro, XtlsManaged macro. 


The XConfigureWindow subroutine, XMoveWindow subroutine, 
XtCreateManagedWidget subroutine, XtCreateWidget subroutine, XtDestroyWidget 
subroutine, XtGetValues subroutine, XtlsSubclass subroutine XtManageChild subroutine, 
XtManageChildren subroutine, XtMapWidget subroutine, XtMoveWidget subroutine, 
XtResizeWidget subroutine, XtSetMappedWhenManaged subroutine, XtSetValues 
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subroutine, XtUnmanageChild subroutine, AE menedee sen subroutine, 
XtUnmapWidget subroutine. 





Enhanced X-Windows Shell Widgets Overview 


Shell widgets hold the top-level widgets of an application that communicate with the window 


manager. Shell widgets are designed to be as invisible as possible. A client application must 
create a shell widget it requires but does not handle the sizing of the widget. 


If a shell widget is resized from the outside, typically by a window manager, the widget 
resizes its child widget automatically. Similarly, if the child widget of the shell widget wants to 
change size, it can make a geometry request to the shell widget to negotiate the size change 
with the outer environment. Client applications should not change the size of their shells 
directly. 


Using Enhanced X-Windows to Define Shell Widgets 
Widgets negotiate size and position with their parent widget. Widgets at the top-level of the 
hierarchy do not have parent widgets. Instead, these widgets must deal with the outside 
world. To provide for this, each top-level widget is encapsulated in a special widget called a 
Shell widget. 


Shell widgets are a subclass of the Composite widget. They encapsulate other widgets and 
allow the encapsulated widgets to avoid the geometry clipping imposed by the standard 
parent-child window relationship. Shell widgets also provide a layer of communication with 
the window manager. 


There are a total of seven classes of shell widgets. Three of the classes are internal and are 
not instantiated or subclassed by client applications. Four of the classes are defined for 
public use. 


The three shell widget classes allocated for internal use are the following: 


Shell Provides the base class for shell widgets and the fields needed for all 
types of shells. The Shell widget class is a direct subclass of the 
CompositeWidgetClass. 

WMShell Contains fields needed by the common window manager protocol. The 


WMShell widget class is a subclass of the Shell widget class. 


VendorShell Contains fields used by vendor-specific window managers. The 
VendorSheii widget ciass is a subclass of the WMShell widget class. 


The four shell widget classes defined for public use are the following: 


OverrideShell Used for shell windows that completely bypass the window manager. A 
pop-up menu shell is an example of this class. The OverrideShell 
widget class is a subclass of the Shell widget class. 


TransientShell Used for shell windows manipulated by the window manager but not 
iconified separately. These shell windows are iconified by the window 
manager only if the main application shell is iconified. A dialog box 
associated with an application shell is an example of this class. The 
TransientShell widget class is a subclass of the VendorShell widget 
class. 


TopLevelShell Used for normal top-level windows. All additional top-level widgets 
required by an application are examples of this class. The 
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TopLevelShell widget class is a subclass of the VendorShell widget 
class. 


ApplicationShell | Used by the window manager to define the top-level window of a 
separate application instance. The ApplicationShell widget class is a 
subclass of the TopLevelShell widget class. 


Using Enhanced X-Windows to Define ShellClassPart Fields 


None of the shell widget classes has the following additional fields: 


typedef struct { caddr_t extension; } ShellClassPart, 
OverrideShellClassPart, WMShellClassPart, 
VendorShellClassPart, TransientShellClassPart, 
TopLevelShellClassPart, ApplicationShellClassPart; 


Shell widget classes have the (empty) shell fields immediately following the composite 
fields. 


The predefined class records and pointers for shells are the following: 


extern SheliClassRec shellClassRec; 

extern OverrideShellClassRec overrideShellClassRec; 
extern WMShellClassRec wmShellClassRec; 

extern VendorShellClassRec vendorShellClassRec; 

extern TransientShellClassRec transientShellClassRec; 
extern TopLevelShellClassRec topLevelShellClassRec; 
extern ApplicationShellClassRec applicationShellClassRec; 


The predefined class pointers for shells are the following: 


extern WidgetClass shellWidgetClass; 

extern WidgetClass overrideShellWidgetClass; 
extern WidgetClass wmShellWidgetClass; 

extern WidgetClass vendorShellWidgetClass; 
extern WidgetClass transientShellWidgetClass; 
extern WidgetClass topLevelShellWidgetClass; 
extern WidgetClass applicationShellWidgetClass; 


The following opaque types and opaque variables are defined for generic operations on 
widgets that are a subclass of the ShellWidgetClass: 


TYPES VARIABLES 

ShellWidget shellWidgetClass 
OverrideShellWidget overrideShellWidgetClass 
WMShellWidget wmShellWidgetClass 
VendorShellWidget vendorShellWidgetClass 
TransientSheliWidget transientShellWidgetClass 
TopLevelShellWidget topLevelShellWidgetClass 
ApplicationShellWidget applicationShellWidgetClass 


ShellWidgetClass 
OverrideShellWidgetClass 
WMShellWidgetClass 
VendorShellWidgetClass 
TransientShellWidgetClass 
TopLevelShellWidgetClass 
ApplicationShellWidgetClass 
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Using Enhanced X-Windows to Define ShellPart Fields 


The various shells have additional fields defined in their widget records. 


The full definitions of the various shell widgets have the shell fields following the composite 
fields: 


Using Enhanced X-Windows Default Values for SheliPart Fields 
Default values for fields common to all classes of public shells are filled in by the Shell 
resource lists and the Shell initialize procedures. 


Related Information 
The ApplicationShellCiassRec data structure, ApplicationShellPart data structure, 
OverrideShellClassRec data structure, OverrideShellPart data structure, ShellClassRec 
data structure, ShellPart data structure, ShellWidget data structure, 
TopLevelShellClassRec data structure, TopLevelShellPart data structure, 
TransientShellClassRec data structure, TransientShellPart data structure, 
VendorShellClassRec data structure, VendorShellPart data structure, WMShellCilassRec 
data structure WMShellPart data structure. 





Enhanced X-Windows Pop-up Widgets Overview 


Pop-up widgets are used to create windows outside of the window hierarchy defined by the 
widget tree. A pop-up is created and attached to its parent widget differently than a standard 
child widget. The window associated with a pop-up child widget is defined as a descendant 
of the root window such that it is not clipped by the parent window of the pop-up widget. 


A parent widget of a pop-up widget does not actively manage its pop-up child widgets. A 
pop-up can be popped up from its parent widget and from other widgets. 


The list of pop-up child widgets of a parent widget is maintained in the popup_list field in the 
CorePart structure of the parent widget. This pop-up list defines placement in the widget 
hierarchy for the pop-up to get resources and provides a list of child widgets for use by the 
XtDestroyWidget subroutine. 


A Composite widget can have both normal and pop-up child widgets. The term child in this 
context refers to a standard geometry-managed child widget on the child widget list. A 
pop-up child widget refers to a child widget on a pop-up list. 


There are three kinds of pop-up widgets , as follows: 


modeiess pop-up Usually visible to the window manager. To the user, this 
pop-up looks like any other application. A modeless dialog box 
is an example of the modeless pop-up. 


modal pop-up Disables user-event processing by the application except for 
events that occur in the pop-up. This pop-up can be visible to 
the window manager. An example of a modal pop-up is a 
modal dialog box. 


spring-loaded pop-up Disables user-event processing by all applications except for 
events that occur in the pop-up. This pop-up is not visible to 
the window manager. An example of a spring-loaded pop-up Is 
a menu. 


Modal pop-ups and spring-loaded pop-ups are similar and should be coded the same. A 
single widget, such as a ButtonBox or a Menu, can be used as a modal pop-up and as a 
spring-loaded pop-up within the same application. The main difference between the modal 


5—180 AIX User Interface Programming Concepts 


pop-up and the spring-loaded pop-up is that each spring-loaded pop-up is brought up with 
the pointer and requires different processing by the Intrinsics library because of the grab 
caused by the pointer button. 


Any kind of pop-up can pop up other widgets. Modal and spring-loaded pop-ups can 
constrain user events to the most recent pop-up or to any modal or spring-loaded pop-ups 
currently mapped. 


Pop-up widget classes are subclasses of the Shell widget class responsible for 
communicating with the window manager. 


Using Enhanced X-Windows to Create a Pop-up Shell 
For a widget to pop up, it must be the child widget of a pop-up widget shell. The pop-up shell 
communicates with the window manager when geometry requests are made. It is also 
responsible for handling the bookkeeping associated with actual pop-up and pop-down 
actions. Each pop-up shell can have only one pop-up child widget. The shell and child 
widgets together are referred to as the pop-up. When a child widget pop-up is required, the 
pop-up shell must be specified. 


To create a pop-up shell, use the XtCreatePopupShell subroutine. This subroutine attaches 
a pop-up shell to the pop-up list of the parent widget. 


A spring-loaded pop-up invoked from a translation table must already exist at the time the 
transaction is called so the translation manager can locate the shell by name. Other pop-ups 
can be created as needed. Creating a pop-up later can be useful when you pop up an 
unspecified number of pop-ups. You can determine if an unused shell or a shell not currently 
popped up exists, and then create a new shell if necessary. 


Using Enhanced X-Windows to Create Pop-up Children 
The child widget of a pop-up shell can be created anytime after the pop-up shell is created. 
The pop-up child widget can be treated as either a static or dynamic entity. 


An application can create the child widget of the pop-up shell at application startup. This 
action is appropriate for pop-up child widgets composed of a fixed set of widgets. The 
application can change the state of the subparts of the pop-up child widget as the application 
state changes. For example, if an application creates a static menu, it can cail the 
XtSetSensitive or the XtSetValues subroutines on any of the buttons that make up the 
menu. Creating the pop-up child widget at application startup means that pop-up time can be 
minimized, especially if the application calls the XtRealizeWidget subroutine on the pop-up 
shell at startup time. When the pop-up child widget is needed, the widgets that make up the 
child widget already exist and only need to be mapped. 


Alternatively, an application can postpone the creation of a pop-up child widget until it is 
needed. This minimizes application startup time and allows the pop-up child widget to 
reconfigure itself dynamically each time it is popped up. In this case, the pop-up child widget 
creation routine polls the application to find out if it should change any of its subparts. 


Creating a pop-up child widget does not map the pop-up. 


All shells have pop-up and pop-down callbacks. These callbacks provide mechanisms to 
make last-minute changes to a pop-up child widget before it is popped up or to change the 
child after it is popped down. Excessive use of pop-up callbacks can slow the pop-up action. 


Using Enhanced X-Windows to Map a Pop-up Widget 


Pop-ups can be popped up and mapped through several mechanisms: 


e Call to the XtPopup subroutine. 
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e Use of a supplied callback such as the XtCallbackNone, the XtCallbackNonexclusive, 
or the XtCallbackExclusive subroutines. 


e Use of the standard MenuPopup translation action. 


A call to the XtPopup subroutine maps a pop-up from within an application. The 
XtCallbackNone, the XtCallbackNonexclusive, and the XtCallbackExclusive subroutines 
map a pop-up from the callback list of a specified widget. The MenuPopup translation 
action pops up a menu when a pointer button is pressed or when the pointer is moved into a 
window defined to produce the menu. 


Using Enhanced X-Windows to Unmap a Pop-up Widget 


Pop-ups can be popped down and unmapped through several mechanisms: 
e Call to the XtPopdown subroutine. 

e Use of the supplied callback XtCallbackPopdown subroutine. 

e Use of the standard MenuPopdown translation action. 


A cail to the XtPopdown subroutine pops down and unmaps a pop-up from within an 
application. The XtCallbackPopdown subroutine pops down and unmaps pop-ups popped 
up by the XtCallbackNone, the XtCallbackNonexclusive, and the XtCallbackExclusive 
subroutines. The MenuPopdown translation action pops down and unmaps a spring-loaded 
menu when a pointer button is released or when the pointer is moved into a window. 


Related Information 
The XtCallbackPopdown callback procedure. 


The CorePart data structure, XtPopdownID data structure. 


The XitCallbackExclusive subroutine, XtCallbackNone subroutine, 
XtCallbackNonexclusive subroutine, XtCreatePopupShell subroutine, XtDestroyWidget 
subroutine, XtPopdown subroutine, XtPopup subroutine, XtRealizeWidget subroutine, 
XtSetSensitive subroutine, XtSetValues subroutine. 


The MenuPopdowrn translation action, MenuPopup translation action. 


Enhanced X-Windows Widget Geometry Overview 


A widget does not directly control its size or location. The position of child widgets is usually 
the responsibility of the narent widget. However, the child widgets often have the best idea of 
their optimal sizes and preferred locations. 


To resolve physical layout conflicts between sibling widgets or a child widget and its parent 
widget, the Intrinsics library provide a geometry management mechanism. Most Composite 
widgets have a geometry_manager field in the widget class record that is responsible for the 
size, position, and stacking order of the child widgets. Exceptions to this are fixed boxes 
which create child widgets and can ensure that these child widgets never initiate a geometry 
request. 


Using Enhanced X-Windows to Initiate Geometry Changes 
Parent widgets, child widgets, and clients initiate geometry changes differently. Because a 
parent widget has absolute control of the geometry of its child widgets, it changes the 
geometry directly by calling the XtMoveWidget, the XtResizeWidget, or the 
XtConfigureWidget subroutine. A child widget must ask its parent widget for a geometry 
change by calling the XtMakeGeometryRequest or the XtMakeResizeRequest subroutine 
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to convey its request to its parent widget. An application or other client code initiates a 
geometry change by calling the XtSetValues subroutine on the appropriate geometry fields, 
thereby giving the widget the opportunity to modify or reject the client request before it gets 
propagated to the parent widget and the opportunity to respond appropriately to the reply of 
the parent widget. 


When the geometry manager of a parent widget received a request from a child widget for a 
change in the child widgets size, position, border width, or stacking depth, the geometry 
manager can do the following: 


e Allow the request 
e Disallow the request 
e Suggest a compromise. 


When the geometry manager is asked to change the geometry of a child widget, the 
geometry manager can also rearrange and resize any or all of the other children widgets that 
it controls. The geometry manager can move child widgets around freely using the 
XtMoveWidget subroutine. When it resizes a child widget other than the one making the 
request, it calls the XtResizeWidget subroutine. The geometry manager can simultaneously 
move and resize a child widget with a single call to the XtConfigureWidget subroutine. 


Often, geometry managers find they can satisfy a request only by reconfiguring a widget 
they do not control, such as when the Composite widget wants to change its own size. In 
this case, the geometry manager makes a request to the geometry manager of the parent. 
Geometry requests can cascade this way to arbitrary depth. 


Because such cascaded arbitration of widget geometry can involve extended negotiation, 
windows are not actually allocated to widgets at application startup until all widgets are 
satisfied with their geometry. 


Note: The Intrinsics library treatment of stacking requests is deficient in several areas. 
Stacking requests for unrealized widgets are granted but will have no effect. In 
addition, there is no way to use the XtSetValues subroutine to generate a stacking 
geometry request. 


Note: After a successful geometry request (one that returns the XtGeometry Yes value), a 
widget does not know whether or not its resize procedure has been called. Widgets 
should have resize procedures that can be called more than once without ill effects. 


Using Enhanced X-Windows to Make General Geometry Manager 
Requests 
To make a general geometry manager request from a widget, use the 
XtMakeGeometryRequest subroutine. 


The return codes from geometry managers are as follows: 


typedef enum XtGeometryResult { 
XtGeometryYes, 
XtGeometryNo, 
XtGeometryAlmost, 
XtGeometryDone, 

} XtGeometryResult; 


Using Enhanced X-Windows in Making Resize Requests 


Use the XtMakeResizeRequest subroutine to make a simple resize request from a widget. 
This subroutine is basically a simple interface to the XtMakeGeometryRequest subroutine. 
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Using Enhanced X-Windows to Manage Potential Geometry Changes 
Sometimes a geometry manager cannot respond to a geometry request from a child widget 
without first making a geometry request to the widget’s own parent widget (the requestor’s 
grandparent widget). If the request to the grandparent widget would allow the parent widget 
to satisfy the original request, the geometry manager can make the intermediate geometry 
request as if it were the originator. 


On the other hand, if the geometry manager already has determined that the original request 
cannot be completely satisfied (for example, if it always denies position changes), it tells the 
grandparent widget to respond to the intermediate request without actually changing the 
geometry because it does not know if the child widget will accept the compromise. To 
accomplish this, the geometry manager uses the XtCWQueryOnly value in the intermediate 
request. 


When the XtCWQueryOnly value is used, the geometry manager needs to cache enough 
information to exactly reconstruct the intermediate request. If the grandparent widgets 
response to the intermediate query is the XtGeometryAlmost return code, the geometry 
manager caches the entire reply geometry in the event that the child widget accepts the 
parent widgets compromise. 


If the grandparent widgets response is the XtGeometryAlmost return code, the entire reply 
geometry from the grandparent widget is cached when the XtCWQueryOnly value is not 
used. If the geometry manager is still able to satisfy the original request, it immediately 
accepts the grandparent widgets compromise and acts on the child widgets request. If the 
grandparent widgets compromise geometry is insufficient to allow the child widgets request 
and if the geometry manager is willing to offer a different compromise to the child widget, the 
grandparent widgets compromise is not accepted until the child widget has accepted the 
new compromise. 


A compromise geometry returned with the XtGeometryAlmost return code is guaranteed 
only for the next call to the same widget. Therefore a cache of size one is sufficient. 


Using Enhanced X-Windows to Manage Child Geometry 
The geometry_manager procedure manages the geometry of a child. The procedure can 
change the x, y, width, height, and border_width values of a widget. The geometry_manager 
procedure pointer in a composite widget class is of the XtGeometryHandler type. 


Sometimes the geometry manager can satisfy change requests only in part or in some 
altered form. For instance, the manager may fill a subset of requests such as size or 
position, or a request in a modified form, such as resizing a widget’s window but not exactly 
to the requested size. 


In such cases, changes are made only if the child widget agrees to the compromises. The 
geometry manager fills in the geometry_return parameter with the actual changes it can 
make, including an appropriate mask, and returns the XtGeometryAlmost return code. If a 
bit in the geometry_return->request_mode is the value of 0, the geometry manager does not 
change the corresponding value if the geometry_return parameter is used immediately in a 
new request. If a bit is one, the geometry manager changes that element to the 
corresponding value in the geometry_return parameter. More bits may be set in the 
geometry_return parameter than in the original request if the geometry manager in set to 
change other fields upon compromise acceptance from the child widget. 


When the XtGeometryAlmost value is returned, the widget must decide if the compromise 
suggested in the geometry_return parameter is acceptable. If it is, the widget makes a call to 
the XtMakeGeometryRequest subroutine to change its geometry. 


The geometry manager must grant the request if the next geometry request from this child 
widget uses the geometry_return parameter box filled in by an XtGeometryAlmost return 
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code, if there have been no intervening geometry requests on either its parent widget or any 
of its other children widgets, and if possible. If the child widget gives its comfirmation 
immediately with the returned geometry, it usually gets an answer of the XtGeometryYes 
return code. However, the user’s window manager can affect the final outcome. 


To return the XtGeometryYes return code, the geometry manager frequently rearranges the 
position of other managed child widgets by calling the XtMoveWidget subroutine. However, 
some geometry managers change the size of other managed child widgets by calling the 
XtResizeWidget or the XtConfigureWidget subroutine. If the XtCWQueryOnly value is 
specified, the geometry manager must return how it will react to this geometry request 
without actually moving or resizing any widgets. 


Geometry managers do not assume that the request and geometry_return parameters point 
to independent storage. The caller is permitted to use the same field for both. The geometry 
manager allocates its own temporary storage if necessary. 


Using Enhanced X-Windows to Manage Widget Placement and Size 
A child widget can be resized by its parent widget at any time. Widgets usually need to know 
when they have changed size so that they can layout their displayed data to match the new 
size. 


If a class need not recalculate anything when a widget is resized, it can specify the value of 
NULL for the resize field in its class record. This case occurs only for widgets with simple 
display semantics. The resize procedure takes a widget as its only argument. The x, y, 
width, height, and border_width fields of the widget contain the new values. The resize 
procedure recalculates the layout of internal data as required. For example, a centered label 
in a window that changes size recalculates the starting position of the text. 


The widget must make changes requested by the resize procedure. A widget must not issue 
an XtMakeGeometryRequest or XtMakeResizeRequest subroutine call from its resize 
procedure. 


The XtResizeWidget subroutine is used to resize a sibling widget of a child widget making a 
geometry request. This procedure updates the geometry fields in the widget, configures the 
window if the widget is realized, and calls the resize procedure of the child widget to notify it 
of the changes. The resize procedure pointer is of the XtWidgetProc type. 


The XtResizeWindow subroutine is used to resize a child widget that already has the new 
values of its width, height, and border width fields. 


The XtConfigureWidget subroutine is used to move and resize a sibling widget of a child 
widget making a geometry request. 


The XtMoveWidget subroutine is used to move a sibling widget of a child widget making a 
geometry request. 


Using Enhanced X-Windows to Handle Preferred Geometry 
Parent widgets can sometimes adjust their layouts to accommodate the preferred 
geometries of their child widgets. They can use the XtQueryGeometry subroutine to obtain 
the preferred geometry and use or ignore any portion of the response. Parent widgets are 
expected to call the XtQueryGeometry subroutine in their layout routine and wherever other 
information is significant after a change_managed procedure is called. 


Related Information 
The XtGeometryResult data structure, XtWidgetGeometry data structure. 


_The XtGeometryHandler data type, XtWidgetProc data type. 
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The XConfigureWindow subroutine, XtConfigureWidget subroutine, 
XtMakeGeometryRequest subroutine, XtMakeResizeRequest subroutine, XtMoveWidget 
subroutine, XtQueryGeometry subroutine, XtRealizeWidget subroutine, XtResizeWidget 
subroutine, XtResizeWindow subroutine, XtSetValues subroutine. 


Enhanced X-Windows Event Manager Overview 


While Enhanced X-Windows allows the reading and processing of events anywhere in an 
application, widgets in the Toolkit can neither directly read events nor grab the server or 
pointer. Widgets register procedures to call when an event or class of events occurs in that 
widget. 


A typical application consists of start-up code followed by an event loop that reads events 
and dispatches them by calling the procedures that widgets have registered. The default 
event loop provided by the Intrinsics library is the XtAppMainLoop subroutine. 


The event manager is a collection of subroutines that: 


e Add or remove event sources other than X Server events, particularly timer interrupts and 
file input. 


e Query the status of event sources. 
e Add or remove procedures to be called when an event occurs for a particular widget. 


e Enable and disable the dispatching of user-initiated events, such as keyboard and pointer 
events, for a particular widget. 


e Constrain the dispatching of events to a cascade of pop-up widgets. 


e Call the appropriate set of procedures currently registered when an event is read. 


Most widgets do not need to call the event handler subroutines explicitly. The normal 
interface to X events is through the higher-level translation manager. The translation 
manager maps sequences of X events, with modifiers, into procedure calls. Applications 
rarely use event manager routines other than the XtAppMainLoop subroutine. 


Using Enhanced X-Windows to Add and Delete Additional Event 


Sources | 


While most applications are driven only by X events, some applications need to incorporate 
other sources of input into the X Toolkit event handling mechanism. The event manager 
provides routines to integrate notification of timer evenis and fiie data that is pending into 
this mechanism. 


Using Enhanced X-Windows to Add and Remove Input Sources 


The XtAppAddinput and the XtRemovelnput subroutines control input gathering from files. 
The application registers the files with the Intrinsics library read routine. When input is 
pending on one of the files, the registered callback procedures are called. 


The XtAppAddinput subroutine registers a new file as an input source for a given 


application. 


The XtRemoveinput subroutine discontinues a source of input. 


Using Enhanced X-Windows to Add and Remove Timeouts 


The timeout facility notifies the application or the widget through a caliback procedure that a 
specified time interval has elapsed. Time-out values are uniquely identified by an interval ID. 
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The XtAppAddTimeOut subroutine creates a timeout value. 


The XtRemoveTimeOut subroutine clears a timeout value. 


Using Enhanced X-Windows to Compress Events Using Event Filters 
The event manager provides filters that can be applied to X user events. The filters screen 
out events that are redundant or temporarily unwanted. These filters handle Pointer motion 
compression, Enter/leave compression, and Exposure compression. 


Using Enhanced X-Windows with Pointer Motion Compression 
Widgets can have a hard time keeping up with pointer motion events and rarely need 
notification of every motion event. Setting the compress_motion widget class field to the 
value of True filters out redundant motion events. With this setting, when a request for an 
event returns a motion event, the Intrinsics library checks for other motion events 
immediately following the current one and ignores all but the last of them. 


Using Enhanced X-Windows with Enter/Leave Compression 
Sometimes pairs of enter and leave events with no intervening events can be ignored. An 
example is when a user moves the pointer across a widget without stopping in it. Setting the 
compress_enterleave widget class field to the value of True filters out pairs of enter and 
leave events with no intervening events. With this setting, enter and leave events are not 
delivered to the client if they are found together in the input queue. 


Using Enhanced X-Windows with Exposure Compression 
Many widgets prefer to process a series of exposure events as a single expose region rather 
than as individual rectangles. Widgets with complex displays might use the expose region as 
a clip list in a graphics context. Widgets with simple displays might ignore the region entirely 
and redisplay their whcle window or get the bounding box from the region and redisplay only 
that rectangle. 


In either case, these widgets do not require information on partial expose events. If the 
compress_exposure field in the widget class structure is set to the value of True, the event 
manager calls the widget’s expose procedure only once for each series of exposure events. 
In this case, all the Expose events are accumulated into a region. When the final Expose 
event in a series (one with count the value of 0) is received, the event manager replaces the 
rectangle in the event with the bounding box for the region and calls the widget’s expose 
procedure, passing the modified exposure event and the region. 


If the compress_exposure field is the value of False, the event manager calls the widget’s 
expose procedure for every exposure event, passing it the event and a region value of 
NULL.. 


Using Enhanced X-Windows to Constrain Events 
Modal widget pop-up lock out user input to an application except direct input to that widget. 


When a modal menu or modal dialog box is popped up using the XtPopup subroutine, user 
events such as keyboard and pointer events that occur outside the modal widget are 
delivered to the modal widget or ignored. In this case, user events are not delivered to a 
widget outside of the modal widget. 


Menus can pop up submenus, and dialog boxes can pop up further dialog boxes to create a 
pop-up cascade. In this case, user events are delivered to one of several modal widgets in 
the cascade. 


Display-related events are delivered outside the modal cascade so that expose events keep 
the application display current. Events that occur within the cascade are delivered normally. 
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User events that are delivered to the most recent spring-loaded shell in the cascade when 
they occur outside the cascade are called remap events. These remap events include the 
KeyPress, KeyRelease, ButtonPress, and ButtonRelease events. The MotionNotify, 
EnterNotify, and LeaveNotify events are ignored if they occur outside the cascade. All 
other events are delivered normally. 


The XtPopup subroutine uses the XtAddGrab and XtRemoveGrab subroutines to 
~ constrain user events to a modal cascade and subsequently to remove a grab when the 
modal widget goes away. There is usually no need to call them explicitly. 


The modal cascade is used by the XtDispatchEvent subroutine when it tries to dispatch a 
user event. When at least one modal widget is in the widget cascade, the XtDispatchEvent 
subroutine first determines if the event should be delivered. It starts at the most recent 
cascade entry and follows the cascade up to and including the most recent cascade entry 
added with the Exclusive parameter set to the value of True. 


This subset of the modal cascade along with all descendants of these widgets is the active 
subset. User events that occur outside the widgets in this subset are ignored or remapped. 
Modal menus with submenus generally add a submenu widget to the cascade with the 
Exclusive parameter set to the value of False. Modal dialog boxes that must restrict user 
input to the most deeply nested dialog box add a subdialog widget to the cascade with the 
Exclusive parameter set to the value of True. User events that occur within the active subset 
are delivered to the appropriate widget, usually a child or further descendant of the modal 
widget. 


Regardless of where they occur on the screen, remap events are always delivered to the 
most recent widget in the active subset of the cascade with its spring_/oaded field set to the 
value of True, if any such widget exists. 


The XtAddGrab subroutine redirects user input to a modal widget. 
The XtRemoveGrab subroutine removes the redirection of user input to a modal widget. 


Using Enhanced X-Windows to Focus Events on a Child 
The XtSetKeyboardFocus subroutine redirects keyboard input to a child widget of a 
Composite widget without calling the XSetInputFocus subroutine. Widgets requiring the 
input focus can call the XSetinputFocus subroutine explicitly. 


To allow outside agents to cause a widget to get the input focus, each widget exports an 
accept_focus procedure. The widget returns whether or not it actually took the focus, so that 
the parent widget can give the focus to another widget. 


Widgets that need to know when they lose the input focus Musi use ihe Xiib iibrary focus 
notification mechanism explicitly by specifying translations for the Focusin and FocusOut 


events. Widgets not requiring information on input focus have their accept_focus procedure 
pointer set to the value of NULL.. 


The XtCallAcceptFocus subroutine calls the accept_focus procedure of a widget. 


Using Enhanced X-Windows to Query Event Sources 
The event manager provides three subroutines to examine and read events, including file 
and timer events, that are in the queue. These subroutines handle the Intrinsics library 
equivalents of the XPending, XPeekEvent, and the XNextEvent subroutines. 


The XtAppPending subroutine determines if there are events on the input queue for a given 
application. 


The XtAppPeekEvent subroutine returns the value from the beginning of the input queue of 
a given application without removing input from the queue. 
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The XtAppNextEvent subroutine returns the value from the beginning of the input queue of 
a given application. 


Using Enhanced X-Windows in Dispatching Events 


The Intrinsics library provides subroutines that dispatch events to widgets or other 
application code. Every client interested in X events on a widget uses the 
XtAddEventHandler subroutine to register which events it is interested in and a procedure 
(event handler) to be called when the event happens in that window. The translation 
manager automatically registers event handlers for widgets that use translation tables. 


The XtAppProcessEvent subroutine gives applications direct control of the processing of 
different types of input. This procedure is not usually called by client applications. The 
XtAppProcessEvent subroutine processes timer events by calling appropriate timer 
callbacks, alternate input by calling appropriate alternate input callbacks, and X events by 
calling the XtDispatchEvent subroutine. 


Using Enhanced X-Windows to Handle the Application Input Loop 


The XtAppMainLoop subroutine handles the processing of input from a given application. 
This procedure controls the main loop of X Toolkit applications and does not return. This 
main loop is basically an infinite loop that first calls the XtAppNextEvent subroutine, and 
then calls the XtDispatchEvent subroutine. Applications exit in response to some user 
action. 


Applications can provide their own version of this loop by testing a global end flag or 
confirming that the number of top-level widgets is larger than 0 before circling back to the 
call to the XtAppNextEvent subroutine. 


Using Enhanced X-Windows to Set and Check the Sensitivity State of a 


Widget 


Many widgets have a mode in which they assume a different appearance (for example, are 
grayed out or stippled), do not respond to user events, and become dormant. When 
dormant, a widget is considered to be insensitive. When a widget is insensitive, the event 
manager does not dispatch events to the widget with a KeyPress, KeyRelease, 
ButtonPress, ButtonRelease, MotionNotify, EnterNotify, LeaveNotify, Focusin, or 
FocusOut event type. 


A widget can be insensitive because its sensitive field is set to the value of False or because 
one of its parents is insensitive, causing the widget’s ancestor_sensitive field to be set to the 
value of False. A widget can but does not need to distinguish these two cases visually. 


The XtSetSensitive subroutine sets the sensitivity state of a widget. 


The XtlsSensitive subroutine checks the current sensitivity state of a given widget. This 
procedure is usually done by the parent widgets. 


Using Enhanced X-Windows to Add Background Work Procedures 


The Intrinsics library have limited support for background processing. Because most 
applications spend most of their time waiting for input, you can register an idle-time work 
procedure to be called when the Toolkit would otherwise block the XtAppNextEvent 
subroutine or the XtAppProcessEvent subroutine. Work procedure pointers are of the 
XtWorkProc type. 


The XtAppAddWorkProc subroutine registers a work procedure for a given application. 
Multiple work procedures can be registered. 


To remove a work procedure, either return the value of True from the procedure when it is 
called or use the XtRemoveWorkProc subroutine. 
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Using Enhanced X-Windows to Handle Widget Exposure and Visibility 
Every primitive widget and some composite widgets display data on the screen by means of 
raw the Xlib library calls. Widgets must keep track of what they write to the screen. They 
must keep enough state to redisplay the window or parts of it if a portion is obscured and 
then redisplayed. 


Using Enhanced X-Windows to Redisplay a Widget 
The redisplay of a widget upon exposure is the responsibility of the expose procedure in the 
class record of the widget. The expose procedure pointer in a widget class is of the 
XtExposeProc type. 


If a widget has no display semantics, it can specify the value of NULL for the expose field. If 
the expose procedure is the value of NULL, the XtRealizeWidget subroutine fills in a default 
bit gravity of NorthWestGravity before it calls the realize procedure of the widget. 


Many composite widgets serve only as containers for their child widgets and have no pees 
expose procedure. 


It often is possible to anticipate the display needs of several levels of subclassing. For 
example, rather than writing separate display procedures for the widgets Label, Command, 
and Toggle, you can write a single display routine in Label that uses display state fields 
like the following: 


Boolean invert 
Boolean highlight 
Dimension highlight_width 


Label would have invert and highlight always the value of False and highlight_width field 
the value of 0. Command would dynamically set the highlight and highlight_width fields, but it 
would leave the invert field always the value of False. Toggle would dynamically set all 
three. In this case, the expose procedures for Command and Toggle inherit the expose 
procedure of their superclass. 


Using Enhanced X-Windows Widget Visibility 
Some widgets use substantial computing resources to display data. However, this resource 
is wasted if the widget is not actually visible on the screen, obscured by another application, 
or iconified. 


The visible field in the Core widget structure tells the widget that it need not display data. 
This field has the value of True by the time an Expose event is processed if the widget is 
visible, but it usually has the value of False if the widget is not visible. 


Widgets can use or ignore the visib/e field. They ignore the field if the visible_interest field in 
their widget class record is set to the value of False. In such cases, the visible field is 
initialized as the value of True and does not change. If the visible_interest field has the value 
of True, the event manager asks for the VisibilityNotify events for the widget and updates 
the visible field accordingly. 


Using Enhanced X-Windows X Event Handlers 
Event handlers are procedures called when specified events occur in a widget. Most widgets 
do not use event handlers explicitly. Instead, they use the Intrinsics library translation 
manager. 


Event handler procedure pointers are of the XtEventHandler type. 
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Using Enhanced X-Windows Event Handlers That Select Events 
The XtAddEventHandler subroutine registers an event handler procedure with the dispatch 
mechanism. This procedure is then called when an event matching the defined mask occurs 
on the specified widget. 


The XtRemoveEventHandler subroutine removes a previously registered event handler. 


Using Enhanced X-Windows Event Handlers That Do Not Select Events 
The XtAddRawEventHandler subroutine enables clients to register an event handler 
procedure with the dispatch mechanism without causing the server to select for that event. It 
functions like the XtAddEventHandler subroutine except that it does not affect the event 
mask of the widget and does not call an XSelectinput subroutine for its events. 


The XtRemoveRawEventHandler subroutine removes a previously registered raw event 
handler. 


Using Enhanced X-Windows to Retrieve a Current Event Mask 
The XtBuildEventMask subroutine retrieves the event mask for a given widget. 


Related Information 
The XtWorkProc data structure. 


The XtAcceptFocusProc data type, XtEventHandler data type, XtExposeProc data type, 
XtinputCallbackProc data type. 


The XtlsSensitive macro. 
The XtTimerCallbackProc procedure. 


The XNextEvent subroutine, XPeekEvent subroutine, XPending subroutine, XSelectInput 
subroutine, XSetInputFocus subroutine, XtAddEventHandler subroutine, XtAddGrab 
subroutine, XtAddRawEventHandler subroutine, XtAppAddInput subroutine, 
XtAppAddTimeOut subroutine, XtAppAddWorkProc subroutine, XtAppMainLoop 
subroutine, XtAppNextEvent subroutine, XtAppPeekEvent subroutine, XtAppPending 
subroutine, XtAppProcessEvent subroutine, XtBuildEventMask subroutine, 
XtCallAcceptFocus subroutine, XtDispatchEvent subroutine, XtPopup subroutine, 
XtRealizeWidget subroutine, XtRemoveEventHandler subroutine, XtRemoveGrab 
subroutine, XtRemovelnput subroutine, XtRemoveRawEventHandler subroutine, 
XtRemoveTimeOut subroutine, XtRemoveWorkProc subroutine, XtSetKeyboardFocus 
subroutine, XtSetSensitive subroutine. 


Enhanced X-Windows Resource Management Overview 


Widget writers need a large set of resources at the time of widget creation. Some resources 
come from the resource database, some from the argument list supplied in the call to the 
XtCreateWidget subroutine, and some from the internal defaults specified for the widget. 
Resources are obtained first from the argument list, then from the resource database for all 
resources not specified in the argument list, and last from the internal default. 

A resource is a field in the widget record with a corresponding resource entry in the widget 
resource list or in the resource list of any of its superclasses. This field can be set by one of 
the following methods: 


e The XtCreateWidget subroutine, by naming the field in the argument list. 
e Anentry in the default resource files, using either the name or class. 


e Using the XtSetValues subroutine. 
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in addition, this field is readable by the XtGetValues subroutine. 


Not all fields in a widget record are resources. Some fields provide bookkeeping for the 
generic routines, such as the managed and being_destroyed fields. Other fields provide local 
bookkeeping while still others are derivations of resources, such as GCs and pixmaps. 


Using Enhanced X-Windows to Create Resource Lists 
A resource entry specifies a field in the widget, the textual name and class of the field that 
argument lists and external resource files use to refer to the field, and a default value that 
the field should get if no value is specified. 


The XtGetResourceList subroutine gets the resource list structure for a particular class. 
The XtSetValues and XtGetValues subroutines use the resource list to set and get the 
widget state. 


The following is an example of an abbreviated version of the resource list in the Label 
widget: 


/*Resources specific to Label*/ 

static XtResource resources[ ] = { 

{XtNforeground, XtCForeground, XtRPixel, 
sizeof(Pixel), XtOffset(LabelWidget, 
label. foreground), XtRString, 
XtDefaultForeground}, 

{XtNfont, XtCFont, XtRFontStruct, sizeof 
(XFontStruct *), XtOffset(LabelWidget, 
label.font), XtRString, XtDefaultFont}, 

{XtNlabel, XtCLabel, XtRString, sizeof(String), 
XtOffset(LabelWidget, label.label), XtRString, NULL}, 


The complete resource name for a field of a widget instance is the concatenation of the 
application name (from the XtAppCreateShell subroutine), the instance names of all the 
parents of the widget up to the ApplicationShellWidget, the instance name of the widget 
itself, and the resource name of the specified field of the widget. 


The full resource class of a field of a widget instance is the concatenation of the application 
class (from the XtAppCreateShell subroutine), the widget class names of all the parents of 
the widget up to the ApplicationShellWidget (not the superclasses), the widget class name 
oi ine widget itself, and the resource name of the specified field of the widget. 


Using Enhanced X-Windows to Chain Resource Lists from Superclass 
to Subclass 
The XtCreateWidget subroutine gets resources as a superclass-to-subclass operation. The 
resources specified in the the Core resource list are called, then those in the subclass are 
called, and so on down to the resources specified for this widget class. Within a class, 
resources are called in the order they are declared. 


Generally, if a widget resource field is declared in a superclass, that field is included in the 
resource list of the superclass and does not need to be included in the resource list of the 
subclass. For example, since the Core class contains a resource entry for the 
background_pixel field, the implementation of the Label widget does not need a resource 
entry for the background_pixel field as well. However, a subclass can override the resource 
entry for any field declared in a superclass by specifying a resource entry for that field in its 
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own resource list. To provide new values that supersede the superclass defaults, override 
the resource entry. At class initialization time, resource lists for that class are scanned from 
the superclass down to the class to look for resources with the same offset. A matching 
resource in a subclass will be reordered to override the superclass entry. A copy of the 
superclass resource list is made to avoid affecting other subclasses of the superclass. 


A widget does not do anything to get its own resources; the XtCreateWidget subroutine 
automatically gets resources for widgets before calling the class initialize procedure. 


Some widgets have subparts that are not widgets but for which the widget needs to get 
resources. For example, the Text widget gets resources for its source and sink. Widgets with 
such needs call the XtGetSubresources subroutine. 


Some widgets also need resources that are not specific to a widget but that apply to the 
overall application. In this case, widgets call the XtGetApplicationResources subroutine. 


Related Information 
The XtConverter data type, XtResource data structure. 


The XtArgsFunc data type, XtResourceDefaultProc data type. 


The XtAppAddConverter subroutine, XtAppCreateShell subroutine, XtConvert 
subroutine, XtCreateWidget subroutine, XtDirectConvert subroutine, 
XtGetApplicationResources subroutine, XtGetResourceList subroutine, 
XtGetSubresources subroutine, XtGetSubvalues subroutine, XtGetValues subroutine, 
XtSetValues subroutine. 
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Enhanced X-Windows Predefined Resource Converters 
Overview 


Using Enhanced X-Windows to 5 Convert Resources 
The Intrinsics library provide a mechanism for registering representation converters that are 
automatically called by the resource calling subroutines. In addition, the Intrinsics library 
provide and register several commonly used converters. The resource conversion - 
mechanism serves several purposes: 


e Permits user and application resource files to contain ASCII representations of 
non-textual values. 


e Allows textual or other representations of default resource values that are dependent 
upon the display, screen, or color map, and thus must be computed at run time. 


e Caches all conversion source and result data. Conversions that require much 
computation or space (for example, string to translation table) or that require round trips 
to the server (for example, string to font or color) are performed only once. 


The Intrinsics library defines all the representations used in the Core, Composite, 
Constraint, and Shell widgets. Furthermore, it registers the following resource converters: 


From To 


XtRString XtRAcceleratorTable, XtRBoolean, XtRBool, XtRCursor, 
XtRDimension, XtRDisplay, XtRFile, XtRFloat, XtRFont, XtRFontStruct, 
XtRint, XtRPixel, XtRPosition, XtRShort, XtRTranslationTable, and 


XtRUnsignedChar 
XtRColor XtRPixel 
XtRint XtRBoolean, XtRBool, XtRColor, XtRDimension, XtRFloat, XtRFont, 
XtRPixel, XtRPixmap, XtRPosition, XtRShort, and XtRUnsignedChar 
XtRPixel XtRColor 


The string to pixel conversion has two predefined constants that work in contrast with each 
other (XtDefaultForeground and XtDefaultBackground). These constants evaluate the 
black and white pixel values of the widget’s screen, respectively. If, however, the application 
uses reverse video, they evaluate the white and black pixel values of the widget’s screen, 
respectively. The string-to-font and font structure converters recognize the XtDefaultFont 
constant and evaulate this to the font in tne Gefauli grapnics coniext of the screen. 


Using Enhanced X-Windows to Write a New Resource Converter 
Type converters use pointers to the XrmValue data structures (defined in the 
<X11/Xresource.h> header file) for input and output values. 


A resource converter procedure pointer is of the XtConverter type. 
Type converters should perform the following actions: 

e Check that the number of arguments passed is correct. 

e Attempt the type conversion. 


e Return a pointer to the data in the fo field if successful. Otherwise, call the 
XtWarningMsg subroutine and return without modifying the fo field. 
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Most type converters take the data described by the specified from field and return data by. 
writing into the specified to field. Some converters need other information, available in the 
specified args field. A type converter can invoke another type converter, allowing differing 
sources that may convert into a common intermediate result to make maximum use of the 
type converter cache. 


The address written in to->addr cannot be a local variable of the converter because this is 
not valid after the converter returns. The address should be a pointer to a static variable, as 
shown in the following example where screenColor is returned. 


The following is an example of a converter that takes a string and converts it to a pixel: 


static void CvtStringToPixel(args, num_args, 
fromVal, toVal) 
XrmValue *args; 
Cardinal *num_args; 
XrmValue *fromVal; 
XrmValue *toVal; 


static XColor screenColor; 
XColor exactColor; 

Screen *screen; 

Colormap colormap; 

Status status; 

char message[1000]; 
XrmQuark q; 

String params{1]; 

Cardinal num_params = 1; 


if (*num_args != 2) 
XtErrorMsg(“cvtStringToPixel”,”“wrongParameters”, 
“XtToolkitError”, “String to pixel 
conversion needs screen and colormap 
arguments”, (String *)NULL,(Cardinal *) NULL); 


screen = *((Screen **) args[{0].addr); 
colormap = *((Colormap *) args[1].addr); 


LowerCase((char *) fromVal->addr,message) ; 
q = XrmStringToQuark(message); 


if(q == XtQExtdefaultbackground) {done(&screen-> 
white pixel, Pixel);return; } 
if(q == XtQExtdefaultforeground) {done(&screen-> 


black_pixel, Pixel);return; } 


if ((char) fromVal->addr&lrbk.0] == '#’') { /* a 
color definition */ 


status = XParseColor(DisplayOfScreen(screen),colormap, 
(String)fromVal->addr, &screenColor); 

if(status != 0) status = XAllocColor 
(DisplayOfScreen(screen), colormap, &screenColor) ; 


} else /* some color name */ 
status = XAllocNamedColor(DisplayOfScreen(screen), 


colormap, (String)fromVal->addr, &screenColor, 
&exactColor); 
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if(status == 0) { 


params[0]J=(String) fromVal->addr; 
XtWarningMsg("“cvtStringToPixel”,”noColormap”, 
“XtToolkitError”, 
“Cannot allocate colormap entry for\"%s\"", 
params, &num_params) ; 


} else { 


toVal->addr 
toVal->size 


(caddr_t)&screenColor.pixel; 
sizeof(Pixel); 


} 
}; 


All type converters should define some set of conversion values that they will succeed on so 
these can be used in the resource defaults. This issue arises only with conversions, such as 
fonts and colors, where there is no string representation that all server implementations will 
necessarily recognize. For resources of this nature, the converter should define a symbolic 
constant, such as XtDefaultForeground, XtDefaultBackground, or XtDefaultFont. 


The code for registering the CvtStringToPixel routine is the following: 


Static XtConvertArgRec colorConvertArgs[] = { 
{XtBaseOffset, (caddr_t) XtOffset(Widget, 
core.screen), sizeof(Screen* ) } 
{XtBaseOffset, (caddr_t) XtOffset(Widget, 
core.colormap), sizeof(Colormap) } 


}3 


XtAddConverter(XtRString, XtRPixel, CvtStringToPixel, 
colorConvertArgs, XtNumber(colorConvertArgs ) ); 


The conversion argument descriptors colorConvertArgs and screenConvertArg are 
predefined. 


e The screenConvertArg descriptor puts the screen field for the widget into the args/0] field. 


e The colorConvertArgs descriptor puts the screen field of the widget into the args/0] field, 
and the widget co/lormap field into the args/1] field. 


Conversion routines should not juSt put a Gescripior for ine address of the base of the widget 
into the args/0] field, and use that in the routine. They should pass the actual values that the 
conversion depends on. By keeping the dependencies of the conversion procedure specific, 
it is more likely that subsequent conversions will find what they need in the conversion — 
cache. This way the cache is smaller and has fewer and more widely applicable entries. 


Using Enhanced X-Windows to Register a New Resource Converter 
To register a new resource converter, use the XtAppAddConverter subroutine. 


For the few type converters that need additional arguments, the Intrinsics conversion 
mechanism provides a method of specifying how these arguments should be computed. The 
XtAddressMode enumerated type and the XtConvertArgRec data structure specify how 
each argument is derived. Both the structure and the type are defined in the 
<X11/Convert.h> header file. 
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Using Enhanced X-Windows to Invoke Resource Converters 
Resource-fetchinging subroutines call resource converters if the user specifies a resource 
that is a different representation from the desired representation or if the widget’s default 
resource value representation is different from the desired representation. Examples of 
resource-calling subroutines are XtGetSubresources and XtGetApplicationResources. 


To invoke conversions, use the XtConvert or XtDirectConvert subroutines. 


Using Enhanced X-Windows to Read and Write Widget State 
Any resource field in a widget can be read or written by a client. When writing, the widget 
decides what changes it will actually allow, and updates all derived fields appropriately. 


The following list describes the subroutines to use for various widget state operations. 


XtGetValues Retrieves the current value of a resource associated with a widget 
instance. 

XtGetSubvalues Retrieves the current value of non-widget resource data associated 
with a widget instance. 

XtSetValues Modifies the current value of a resource associated with a widget 
instance. 

XtSetSubvalues Sets the current value of a non-widget resource associated with a 


widget instance. 


Using Enhanced X-Windows to Format Resource Files 
A resource file contains text representing the default resource values for an application or 
set of applications. The resource file is an ASCIl text file that consists of a number of lines 
with the following EBNF syntax: 


Xdefault = {line “\n"”}. 

line = (comment | production). 

comment = "“!" string. 

production = resourcename “:" string. 
resourcename = [“*"] name {(”.” | “*”) name}. 
string = {<any character not including eol>}. 
name = fh Al ae | Haningt | 0) eat OM 


If the last character on a line is a\ (backslash), that line is assumed to continue on the next 
line. To include a new-line character in a string, use “—n.” 


Related Information 
The XrmValue data structure, XtConvertArgRec data structure. 


The XtAlmostProc data type, XtArgsFunc data type, XtConverter data type, 
XtSetValuesFunc data type. 


The XtAddressMode enumerated type. 


The XtAppAddConverter subroutine, XtConvert subroutine, XtDirectConvert subroutine, 
XtGetApplicationResources subroutine, XtGetSubresources subroutine, 
XtGetSubvalues subroutine, XtGetValues subroutine, XtSetSubvalues subroutine, 
XtSetValues subroutine, XtWarningMsg subroutine. 
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Enhanced X-Windows Translation Management Overview 


Except under unusual circumstances, widgets do not hardwire the mapping of user events 
into widget behavior by using the event manager. Instead, they provide a default that can be 
overridden by the user. 





The translation manager provides an interface to specify and manage the mapping of 
Enhanced X-Windows event sequences into widget-supplied functionality; for example, 
calling the Abc procedure when the Y key is pressed. 


The translation manager uses two kinds of tables to perform translations: 


Action table This is in the widget class structure, and specifies the mapping of 
externally available procedure name strings to the corresponding 
procedure implemented by the widget class. 


Translation table —_ This is also in the widget class structure, and specifies the mapping of 
event sequence to procedure name strings. 


You can override the translation table in the class structure for a specific widget instance by 
supplying a different translation table for the widget instance. The resource name is 
XtNtranslations. 


Using Enhanced X-Windows Action Tables 
All widget class records contain an action table. In addition, an application can register its 
own action tables with the translation manager, so that the translation tables it provides to 
widget instances can access application functionality. 


The action table of the application uses the XtActionsRec data structure. 
For example, the Command widget has procedures to: 

e Set the command button to indicate it is activated 

e Reset the command button to its normal mode 

e Highlight the button borders 

e Unhighlight the button borders 

e Notify any callbacks that the button has been activated. 


The action table for the Command widget class makes these functions available to 
translation tables written for Command or any subclass. The string entry is the name used in 
translation tables. The procedure entry, which is usually spelled the same as the string, is 
the name of the C language procedure that implements that function: 


XtActionsRec actionTable[] = { 


{"Set”, Set}, 
{”"Unset”, Unset}, 
{"Highlight”, Highlight}, 
{”"Unhighlight”, Unhighlight}, 
{"Notify”, Notify} 


‘3 


To declare an action table and register it with the translation manager, use the 
XtAppAddActions subroutine. 
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Using Enhanced X-Windows to Translate Action Names to Procedures 
The translation manager uses a simple algorithm to convert the name of a procedure 
specified in a translation table to the actual procedure specified in an action table. When the 
widget is realized, it performs a search for the name in the following tables: 


e The widget’s class action table for the name 
e The widget’s superclass action table and on up the superclass chain 


e The action tables registered with the XtAddActions subroutine, from the most recently 
added table to the oldest table. 


The translation manager stops the search as soon as it finds a name. If no name is found, it 
generates an error. 


Using Enhanced X-Windows Translation Tables 
All widget instance records contain a translation table. A translation table specifies the action 
procedures called for an event or a sequence of events. The table is a string containing a list 
of translations from an event or an event sequence to one or more action procedure calls. 
The translations are separated from one another by new-line characters (ASCII LF). The 
translation table has no default value. 


For example, the default behavior of Command is the following: 


Highlight on enter window 


Unhighlight on exit window 


Invert on left button down 


Call callbacks and reinvert on left button up. 
The default translation table for Command is the following: 


static String defaultTranslations = 


“<EnterWindow>: Highlight()\n\ 
<LeaveWindow>: Unhighlight()\n\ 
<Btn1lDown>: Set()\n\ 

<BtnlUp>: Notify() Unset()”; 


The tm_table field of the CoreClass record should be filled in at the time of static 
initialization with the string containing the default translations of the class. If a class must 
inherit the translations of its superclass, it can store the special value XtInheritTranslations 
into the tm_table field. After the class initialization procedures have been cailed, the 
Intrinsics library compile this translation table into an efficient internal form. Then, at widget 
creation time, this default table is used for any widgets that have not had their Core 
translations field set by the resource manager or the initialize procedures. 


The resource conversion mechanism automatically compiles string translation tables that are 
resources. If a client uses translation tables that are not resources, it must compile them 
using the XtParseTranslationTable subroutine. 


The Intrinsics use the compiled form of the translation table to register the necessary events 
with the event manager. Widgets need to specify only the action and translation tables for 
events to be processed by the translation manager. 


Using Enhanced X-Windows Event Sequences 
An event sequence is a comma-separated list of the Enhanced X-Windows event 
descriptions that describes a specific order of X events to map to a set of program actions. 
Each of these event descriptions consists of the followiing three parts: 
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e The X event type 
e Aprefix consisting of the modifier bits 
e Anevent-specific suffix. 


Various abbreviations can be used to make translation tables easier to read. 


Using Enhanced X-Windows Action Sequences 
Action sequences specify which program or widget actions to take in response to incoming 
events. An action sequence contains a series of action procedure call specifications, each of 
which gives the name of an action procedure and a list of string parameters, in parentheses, 
to pass to that procedure. 


Using Enhanced X-Windows to Merge Translation Tables 
Sometimes an application needs to add its own translations in place of or in addition to the 
translation of the widget. For example, a window manager provides subroutines to move a 
window. Normally, this window manager can move the window when any pointer button is 
pressed down in a title bar. It allows the user to specify other translations for the middle or 
right button down in the title bar, but it ignores any user translations for left button down. 


To accomplish this, the window manager should first create the title bar and then merge the 
two translation tables into the title bar’s translations. One translation table contains the 
translations that the window manager wants if the user has not specified a translation for a 
particular event or event sequence. The other translation table contains the translations that 
the window manager wants regardless of what the user has specified. 


Three subroutines support this merging: 
XtParseTransiationTable Compiles a translation table. 


XtAugmenttTranslations Nondestructively merges a compiled translation table into 
the existing widget translations. 


XtOverrideTranslations Destructively merges a compiled translation table into the 
existing widget translations. 


Using Enhanced X-Windows to Change Translation Tables 
To replace a widget’s translations completely, use the XtSetValues subroutine on the 
XtNtranslations resource and specify a compiled translation table as the value. 


To make it possible to easily modify translation tables in resource files, the 
string-to-translation-table resource type converter allows specification of whether the table 
repiaces, augments, or overrides any existing transiation table in the widget. To do this, the 
first character in the table should be a # (number sign), followed by replace (the default 
action), augment, or override, to indicate whether to replace, augment, or override any 
existing table. 


To completely remove existing translations, use the XtUninstallTranslations subroutine. 


Using Enhanced X-Windows Accelerators 
Applications often need to be able to bind events in one widget to actions in another, such as 
invoking menu actions from the keyboard. To accomplish this, the Intrinsics library provide 
accelerators. An accelerator is a translation table that is bound with its actions in the context 
of a particular widget. The accelerator table can then be installed on a destination widget, 
which allows an action in the destination widget to execute an accelerator action as if it were 
triggered in the accelerator widget. 
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Each widget instance contains that widget’s exported accelerator table. Each class of widget 
exports a method that takes a displayable string representation of the accelerators so that 
the widgets can display their current accelerators. The representation is the accelerator table 
in canonical representation form. 


Use these routines to perform the following accelerator function: 


XtParseAcceleratorTable Parses an accelerator table. 
XtinstallAccelerators Installs accelerators from one widget onto another widget. 
XtinstallAllAccelerators Installs all accelerators from one widget and all of its 


descendants onto one destination. 


Using Enhanced X-Windows to Convert Key Codes to KeySyms 
The XtKeyProc data type specifies the interface definition for user defined 
KeyCode-to-KeySym translator procedures. A KeyCode-to-KeySym translator procedure 
takes a key code and modifiers and produces a key symbol. For any specified key translator 
function, the ModifiersReturn parameter will be a constant that indicates the subset of all 
modifiers examined by the key translator. 


The translation manager provides support for automatically translating key codes in 
incoming key events to KeySyms. 


The following key code translation operations are possible: 
XtSetKeyTranslator Registers a key translator. 


XtRegisterCaseConverter Registers a case converter. Pointers to case conversion 
procedures are of the XtCaseProc data type. 


XtConvertCase Determines the uppercase and lowercase equivalents for a 
KeySym. 

XtTranslateKeycode Invokes the currently registered Keycode-to-KeySym 
translator. 


Using Enhanced X-Windows Translation Table File Syntax 
A translation table file is an ASCII text file. The proper notation and syntax as well as 
common modifier names, event type values, supported abbreviations, canonical 
representations, and examples are found in the sections that follow. 


Using Enhanced X-Windows Notation 
Syntax is specified in EBNF notation with the following conventions: 


[a] Means either nothing or “a” 

{ a } Means 0 or more occurrences of “a” 

All terminals are enclosed in “” (double quotes). Informal descriptions are enclosed in <> 
(angle brackets). 


Using Enhanced X-Windows Syntax 


The syntax of the translation table file is: 


translationTable = [ directive ] { production } 

directive = (“#replace” | “foverride” | “#augment”) “\n” 
production = Ihs “:” rhs “\n” 

Ihs = (event | keyseq) { “,” (event | keyseq) } 
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_ keyseq = ““ keychar {keychar} ”” 


_keychar = [ “4” | “$” ‘\"] <ISO Latin 1 character> 

event . = [modifier_list] “<"event_type">” [“(“count[“+']’)’] {detail} 
‘modifier_list = ([“! |“) {modifier} )| “None” 

modifier = [“~”] modifier_name 

count = (“1” | “2” | “3” | “4” |...) 

modifier_name = “@” <keysym> | <see the ModifierNames table that follows> 
event_type = <see the Event Types table that follows> 

detail = <event specific details> 

rhs = {name “(“ [params] ”)” } 

name = namechar { namechar } 

namechar | = { “a’-“2” | “A”-“Z” | “0”-"9” | “$” | “_” 

params = String {",” string}. 

string = quoted_string | unquoted_string 

quoted_string = “““ {<Latin1 character>} ”” 

unquoted_string = {<Latini character except space, tab, “,”, newline, “)”>} 


It is often convenient to include newlines in a translation table to make it more readable. In C 
language, indicate a newline with a “\n”: 


“<BtnlDown>: DoSomething()\n\ 
<Btn2Down>: DoSomethingElse()” 


Using Enhanced X-Windows Modifier Names 
- The modifier field is used to specify normal Enhanced X-Windows keyboard and button 
modifier mask bits. Modifiers are allowed on the KeyPress, KeyRelease, ButtonPress, 
ButtonRelease, MotionNotify, EnterNotify, LeaveNotify event types and their 
abbreviations: 


An error occurs when a translation table that contains modifiers for any other events is 
parsed. 


e Modifiers don't care if the modifier _listtieid nas no entries and is not the value of None. 


e Listed modifiers must be in the correct state and “don’t care” about any other modifers if 
any modifiers are specified and an ! (exclamation point) is not specified. 


e Listed modifers must be in the correct state and no other modifers can be asserted if an ! 
(exclamation point) is specified at the beginning of the modifier list. 


e Modifiers preceded by a ~ (tilde) must not be asserted. 
e Modifiers cannot be asserted if the value of None is specified. 


e Standard modifiers in the event, which map the event key code into a keysym, are applied 
by the Intrinsics when a : (colon) is specified at the beginning of the modifier list. 


The default standard modifiers are the Shift and Lock keys. The resulting keysym must 
exactly match the specified keysym, and the nonstandard modifiers in the event must 
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match the modifier_list. For example, “:<Key>a’” is different from “<Key>A” and 
“:Shift<Key>A’ is different from “:<Key>A”. 


e No standard modifiers are applied when a : (colon) is not specified. This makes “<Key>A” 
and “<Key>a”, for example, equivalent. 


In key sequences, a “ (circumflex) is an abbreviation for the Control modifier; a $ (dollar 
sign) is an abbreviation for Meta; and a \ (backslash) is used to quote any character, in 
particular a ” (double quote), a ~ (circumflex), a $ (dollar sign), or another \ (backslash). In 
brief: 


No Modifiers: None <event> detail 

Any Modifiers: <event> detail 

Only these Modifiers: !mod1 mod2 <event> detail 
These modifiers and any others: mod1 mod2 <event> detail 


Using None for a modifier_list is the same as using an exclamation point with no modifiers. 


Modifier Abbreviation Meaning 

Ctrl c Control modifier bit 
Shift s Shift modifier bit 
Lock | Lock modifier bit 
Meta m Meta key modifier* 
Hyper h Hyper key modifier* 
Super su Super key modifier* 
Alt a Alt key modifier* 
Mod1 Mod1 modifier bit 
Mod2 Mod2 modifier bit 
Mod3 Mod3 modifier bit 
Mod4 Mod4 modifier bit 
Mod5 Mod5 modifier bit 
Button1 Button1 modifier bit 
Button2 Button2 modifier bit 
Button3 Button3 modifier bit 
Button4 Button4 modifier bit 
Button5 Button5 modifier bit 
ANY Any combination 


*A key modifier is any modifier bit whose corresponding key code contains the 
corresponding left or right keysym. 


For example, m of Meta means any modifier bit that maps to a key code whose keysym list 
contains XK_Meta_L or XK_Meta_R. This interpretation applies for each display, not 
globally or for each application context. The Control, Shift, and Lock modifier names refer 
explicitly to the corresponding modifier bits, and there is no additional interpretation of 
keysyms for these modifiers. 


Because arbitrary keysyms can be associated with modifiers, the set of modifier key 
modifiers is extensible. The “@” <keysym> syntax means any modifier bit whose 
corresponding key code contains the specified keysym. 


A modifier_list/keysym combination in a translation is matched with a modifiers/keycode 
combination in an event as follows: 


If a : (colon) is used, the Intrinsics library call the registered XtKeyProc subroutine (the 
default subroutine is the XtTranslateKey subroutine) for the display with the keycode and 
modifiers. For a match to occur, (modifiers and ~modifiers_return) must equal modifier_list 
and keysym_return must equal the given keysym. 


If a colon is not used, the Intrinsics masks off all don’t care bits from the modifiers. The value 
must be equal to modifier_list. Then, for each possible combination of don’t care modifiers in 
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the modifier_list field, the Intrinsics call the registered XtKeyProc subroutine for that display 
with the keycode and that combination OR’d with the cared-about modifier bits from the 
event. The keysym_return field must match the keysym in the translation. 


Using Enhanced X-Windows Event Types 
The EventType field describes the XEvent types. The currently defined EventType values 
are the following: 


Event Type Value 


Key 
KeyDown KeyPress 
Key Up KeyRelease 
BtnDown ‘ButtonPress. 
BtnUp ButtonRelease 
Motion MotionNotify 
PtrMoved 
MouseMoved 
Enter EnterNotify 
EnterWindow 
Leave LeaveNotify 
LeaveWindow 
Focusin Focusin 
FocusOut FocusOut 
_Keymap KeymapNotify 
Expose Expose 
GrExp GraphicsExpose 
NoExp NoExpose - 
Visible VisibilityNotify 
Create CreateNotify 
Destroy DestroyNotify 
Unmap UnmapNotify 
Map MapNotify 
MapReq MapRequest 
Reparent ReparentNotify 


~ Configure ConfigureNotify 


| ConfigureReq ConfigureRequest 


Grav GravityNotify - 

_ ResReq ResizeRequest 
Circ CirculateNotify 
CircReq CirculateRequest 
Prop PropertyNotify 


5—204 AIX User Interface Programming Concepts 


SelClr 
SelReq 
Select 
Cirmap 
Message 
Mapping 


SelectionClear 
SelectionRequest 
SelectionNotify 
ColormapNotify 
ClientMessage 
MappingNotify 


Using Enhanced X-Windows Supported Event Type Abbreviations 
The detail field is event-specific and corresponds normally to the detail field of an XEvent, 
for example, <key>A. If no detail field is specified, then ANY is assumed. The supported 
abbreviations are the following: 


Abbreviation 


Ctri 

Meta 

Shift 
Btn1Down 
BtniUp 
Btn2Down 
Btn2Up 
Btn3Down 
Btn3Up 
Btn4Down 
Btn4Up 
Btn5Down 
Btn5Up 
BtnMotion 
Btn1Motion 
Btn2Motion 
Btn3Motion 
Btn4Motion 
Btn5Motion 


Meaning 


KeyPress with control modifier 
KeyPress with meta modifier 
KeyPress with shift modifier 
ButtonPress with Btn1 detail 
ButtonRelease with Btn1 detail 
ButtonPress with Btn2 detail 
ButtonRelease with Btn2 detail 
ButtonPress with Btn3 detail 
ButtonRelease with Btn3 detail 
ButtonPress with Btn4 detail 
ButtonRelease with Btn4 detail 
ButtonPress with Btn5 detail 
ButtonRelease with Btn5 detail 
MotionNotify with any button modifier 
MotionNotify with Button1 modifier 
MotionNotify with Button2 modifier 
MotionNotify with Button3 modifier 
MotionNotify with Button4 modifier 
MotionNotify with Button5 modifier 


A keysym can be specified as any of the standard keysym names: as a hexadecimal number 
prefixed with Ox or OX, as an octal number prefixed with 0, or as a decimal number. A 
keysym expressed as a single digit is interpreted as the corresponding Latin1 keysym. For 
example, 0 is the keysym xK_0. Other single character keysyms are treated as literal 
constants from Latin1. For example, ! is treated as 0x21. Standard keysym names are 
those defined in the <X11/keysymdef.h> header file, with the XK_ prefix removed. 
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Using Enhanced X-Windows Canonical Representation 
Every translation table has a unique, canonical text representation. This representation is 
passed to a widget’s display_accelerator method to describe the accelerators installed on 
that widget. (The syntax of a translation table file is described in Using Enhanced 
X-Windows Syntax. The canonical representation of a translation table is the following: 


translationTable 


production 
Ihs 

event 
modifier_list 
modifier 
count 


modifier_name 


event_type 


detail 

rhs 

name 
namechar 
params 

string 
quoted_string 


= { production } 
= lhs “:” rhs “\n” 


= event { “,” event } 


= [modifier_list] “<"event_type“>” [“("count[“+"]})”] {detail} 


= [“! | “:” ] {modifier}) 
= [“~”] modifier_name 
= Ce | e | «3” | “4” | ey 


= “@” <keysym> | The canonical modifier names are: 


Ctrl 
Lock 
Shift 


Button! Mod1 
Button2 Mod2 
Button3 Mod3 
Button4 Mod4 
Button5 Mod5 


= The canonical event types are the following: 


KeyPress 
ButtonPress 
MotionNotify 
EnterNotify 
Focusin 

Expose 
NoExpose 
CreateNotify 
UnmapNotify 
MapRequest 
ConfigureNotify 
GravityNotify 
CirculateNotify 
PropertyNotify 
SelectionRequest 
ColormapNotify 


= <event specific details> 
= {name i [params] “” } 


= namechar { namechar } 


KeyRelease 
ButtonRelease 
LeaveNotify 
KeymapNotify 
FocusOut 
GraphicsExpose 
VisibilityNotify 
DestroyNotify 
MapNotify 
ReparentNotify 
ConfigureRequest 
ResizeRequest 
CirculateRequest 
SelectionCiear 
SelectionNotify 
ClientMessage 


= { fahitign | “A”-“7” | *9”-"Q” | “$” | part } 


= String {“,” string}. 
= quoted_string 


= “““{<Latin1 character>}”” 
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Using erence’ X-Windows Examples of Event Types 
Put more specific events in the table before more general events: 


Shift <BtnlDown> : twas()\n\ 
<BtnlDown> : brillig() 


e For double-click on Button 1 Up with Shift, use: 
Shift<BtnlUp>(2) : and() 
This is equivalent to: 


Shift<Btn1Down>, Shift<BtnlUp>,Shift<BtnlDown>, 
Shift<BtnlUp> : and() 


with appropriate timers set between events. 

e For double-click on Button 1 Down with Shift use: 
Shift<BtnlDown>(2) : the() 
It is equivalent to: 
Shift<Btn1lDown>,Shift<BtnlUp>,Shift<BtnlDown> : the() 
with appropriate timers set between events. 


e Mouse motion is always discarded when it occurs between events in a table where no 
motion event is specified: 


<BtnlDown>,<BtnlUp> : slithy() 


This is taken, even if the mouse jiggles a bit between the down and up events. Similarly, 
any motion event specified in a translation matches any number of motion events. If the 
motion event causes an action procedure to be invoked, the procedure is invoked after 
each motion event. 


e Ifan event sequence consists of a sequence of events that is also a non-initial 
subsequence of another translation, it is not taken if it occurs in the context of the longer 
sequence. This usually occurs in the following types of sequences: 


<BtnlDown>,<BtnlUp> : toves()\n\ 
<BtnlUp> : did() 


The second translation is taken only if the button release is not preceded by a button 
press or if there are intervening events between the press and release sequence. This 
precaution is especially useful when using the repeat notation with buttons and keys 
because their expansion includes additional events and when specifying motion events 
because they are included between any two other events. In particular, mouse motion and 
double-click translations cannot exist in the same translation table. 


e For single click on Button 1 Up with Shift and Meta, use: 
Shift Meta<BtnlDown>, Shift Meta<BtnlUp>: gyre() 


e The “+” notation allows you to indicate “for any number of clicks greater than or equal to 
count”, such as: 


Shift <BtnlUp>(2+): and() 
e To indicate EnterNotify with any modifiers, use: 
<Enter> : gimble() 


e To indicate EnterNotify with no modifiers, use: 
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None <Enter> : in() 


e To say EnterNotify with Button 1 Down and Button 2 Up and don’t care about the other 
modifiers, use: 


Buttonl ~Button2 <Enter> : the() 

e To say EnterNotify with Button1 Down and Button2 Down exclusively, use: 
! Buttonl Button2 <Enter> : wabe() 
You do not need to use a ~ (tilde) with an ! (exclamation point). 


Related Information 
The XtActionProc procedure pointer. 


The XtActionsRec data structure, XtCaseProc data type, XtKeyProc data type, 
XtStringProc data type. 


The XtAppAddActions subroutine, XtAugmentTranslations subroutine, XtConvertCase 
subroutine, XtlnstallAccelerators subroutine, XtInstallAllAccelerators subroutine, 
XtOverrideTranslations subroutine, XtParseAcceleratorTable subroutine, 
XtParseTranslationTable subroutine, XtRegisterCaseConverter subroutine, 
XtSetKeyTranslator subroutine, XtSetValues subroutine, XtUninstallTranslations 
subroutine. 





Enhanced X-Windows Utility Subroutines Overview 


The Enhanced X-Windows Toolkit provides a number of utility functions for Memory 
management, Graphics Contexts sharing, Merging Expose and Graphics Expose events, 
and Error handling. 


Using Enhanced X-Windows to Manage Memory 
The Toolkit memory management routines provide uniform checking for the value of NULL 
pointers and error reporting on memory allocation errors. These routines are completely 
compatible with the standard C language run time routines malloc, calloc, realloc, and free 
with this added functionality: 


e The XtMalloc, the XtNew, the XtCalloc, and the XtRealloc subroutines return an error if 
there is insufficient memory. 

e The XtFree subroutine returns if the value of NULL pointer is passed. 

* The Xifeaiioc subroutine aliocates new storage if the value of NULL pointer is passed. 


Using Enhanced X-Windows to Share Graphics Contexts 
The Toolkit provides a mechanism that allows clients to share Graphics Contexts (GCs), 
reducing both the number of GCs created and the number of calls to the server in an 
application. The XtGetGC subroutine obtains shared GCs. The GCs must be read-only 
when using the XtGetGC subroutine. If a changeable GC is needed, use the XCreateGC 
subroutine instead. 


Using Enhanced X-Windows to Merge Exposure Events into a Region 
The Toolkit provides the XtAddExposureToRegion subroutine that merges the Expose and 
GraphicsExpose events into a region that clients can process at once, rather than 
processing individually. 
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Using Enhanced X-Windows to Handle Errors 
The Toolkit allows a client to register a procedure which is called when an error occurs. This 
facility reports and logs errors, but does not correct them or help you recover. 


Related Information 
The XtErrorMsgHandler data type. 


The XCreateGC subroutine, XtAddExposureToRegion subroutine XtAppError subroutine, 
XtAppErrorMsg subroutine, XtAppGetErrorDatabase subroutine, 
XtAppGetErrorDatabaseText subroutine, XtAppSetErrorHandler subroutine, 
XtAppSetErrorMsgHandler subroutine, XtAppSetWarningHandler subroutine, 
XtAppSetWarningMsgHandler subroutine, XtAppWarning subroutine, 
XtAppWarningMsg subroutine, XtCalloc subroutine, XtFree subroutine, XtGetGC 
subroutine, XtMalloc subroutine, XtNew subroutine, XtNewString macro, XtRealloc 
subroutine XtReleaseGC subroutine. 


List of Enhanced X-Windows Toolkit Data Structures 


The ApplicationShellClassRec data structure. 
The ApplicationShellPart data structure. 
The ApplicationShellWidget data structure. 
The CompositeClassPart data structure. 
The CompositePart data structure. 

The ConstraintClassPart data structure. 
The ConstraintPart data structure. 

The CoreClassPart data structure. 

The CorePart data structure. | 
The OverrideShellClassRec data structure. 
The OverrideSheilPart data structure. 

The OverrideShellWidget data structure. 
The SheilClassRec data structure. 

The ShelliPart data structure. 

The ShellWidget data structure. 

The TopLevelShellClassRec data structure. 
The TopLevelShellPart data structure. 

The TopLevelShellWidget data structure. 
The TransientShellClassRec data structure. 
The TransientShellPart data structure. 

The TransientShellWidget data structure. 
The VendorShellClassRec data structure. 
The VendorShellPart data structure. 

The VendorShellWidget data structure. 

The WMShellClassRec data structure. 

The WMShellPart data structure. 

The WMShellWidget data structure. 

The XrmValue data structure. 

The XtAcceptFocusProc data type. 

The XtActionProc procedure pointer. 

The XtActionList data structure. 

The XtAddressMode enumerated type. 

The XtAlmostProc data type. 

The ArgList data structure. 

The XtArgsFunc data type. 

The XtArgsProc data type. 
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The XtCallbackList data structure. 

The XtCallbackProc data type. 

The XtCaseProc data type. 

The XtConvertArgRec data structure. 
The XtConvertSelectionProc data type. 
The XtConverter data type. 

The XtErrorHandler data type. 

The XtErrorMsgHandler data type. 

The XtEventHandler data type. 

The XtExposeProc data type. 

The XtGeometryHandler data type. 
The XtGeometryResult data structure. 
The XtlnitProc data type. 

The XtinputCallbackProc data type. 
The XtKeyProc data type. 

The XtLoseSelectionProc data type. 
The XtOrderProc data type. 

The XtPopdownID data structure. 

The XtProc data type. 

The XtRealizeProc data type. 

The XtResource data structure. 

The XtResourceDefaultProc data type. 
The XtSelectionCallbackProc data type. 
The XtSelectionDoneProc data type. 
The XtStringProc data type. 

The XtTimerCallbackProc procedure. 
The XtWidgetClassProc data type. 
The XtWidgetGeometry data structure. 
The XtWidgetProc data type. 

The XtWorkProc data structure. 


CoreClassPart Data Structure 


The common fields for all widget classes are defined in the CoreClassPart data structure: 
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typedef struct { 
WidgetClass superclass; 
String class_name; 
Cardinal widget_size; 
XtProc class_initialize; 
XtWidgetClassProc class _part_initialize; 
Boolean class_inited; 
XtInitProc initialize; 
XtArgsProc initialize hook; 
XtRealizeProc realize; 
XtActionList actions; 
Cardinal num_actions; 
XtResourceList resources; 
Cardinal num_resources; 
XrmClass xrm_class; 
Boolean compress_motion; 
Boolean compress_exposure; 
Boolean compress_enterleave; 
Boolean visible interest; 
XtWidgetProc destroy; 
XtWidgetProc resize; 
XtExposeProc expose; 
XtSetValuesFunc set_values; 
XtArgsFunc set_values_hook; 
XtAlmostProc set_values_almost; 
XtArgsProc get_values_hook; 
XtAcceptFocusProc accept focus; 
XtVersionType version; 
_XtOffsetList callback_private; 
String tm_table; 
XtGeometryHandler query geometry; 
XtStringProc display accelerator; 
caddr_t extension; 

} CoreClassPart; 


Related Information 
The XtArgsFunc data type. 





CorePart Data Structure 


The common fields for all widget instances are defined in the CorePart structure: 
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typedef struct CorePart { 
Widget self; 
WidgetClass widget_class; 
Widget parent; 
XrmName xrm_name; 
Boolean being destroyed; 
XtCallbackList destroy callbacks; 
caddr_t constraints; 
Position x; 
Position y; 
Dimension width; 
Dimension height; 
Dimension border_width; 
Boolean managed; 
Boolean sensitive; 
Boolean ancestor sensitive; 
XtEventTable event_table; 
XtTMRec tm; 
XtTranslations accelerators; 
Pixel border_pixel; 
Pixmap border_pixmap; 
WidgetList popup list; 
Cardinal num_popups; 
String name; 
Screen *screen; 
Colormap colormap; 
Window window; 
Cardinal depth; 
Pixel background_pixel; 
Pixmap background_pixmap; 
Boolean visible; 
Boolean mapped_when_managed; 

} CorePart; 


The default values for the core fields are filled in by the Core resource list and the Core 
initialize procedure. The default values for the CorePart data structure are: 


Address of the widget structure (may not be changed) 


widget_class widget_class argument to the XtCreateWidget 
subroutine (may not be changed) 
parent parent argument to the XtCreateWidget subroutine 
(may not be changed) 
xrm_name Encoded name argument to the XtCreateWidget sub- 
routine (may not be changed) 


ee 
aS (caer 
wath 
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height 
border_width 
managed 



















False 
sensitive True 


ancestor_sensitive Bitwise AND of sensitive & ancestor_sensitive fields of 


the parent widget 

Initialized by the event manager 
Initialized by the translation manager 
NULL 

border_pixel XtDefaultForeground 
border_pixmap NULL 


[mumpoowes[O 
The name argument to the XtCreateWidget subrou- 
tine (may not be changed) 


screen Parent screen; top-level widget uses display specifier 
(may not be changed) 


Default colormap for the screen 
NULL 


depth Parent's depth; top-level widget uses root window 
depth 


event_table 
t 
accelerators 


ini 








CompositeClassPart Data Structure 


In addition to the Core widget class fields, Composite widgets have the following class 
fields: 


typedef struct { 
XtGeometryHandler geometry manager; 
XtWidgetProc change_managed; 
XtWidgetProc insert_child; 
XtWidgetProc delete child; 
caddr_t extension; 

} CompositeClassPart; 


Related Information 
The CompositePart data structure. 
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CompositePart Data Structure 


In addition to the CorePart fields, Composite widgets have the following fields defined in 
’ the CompositePart structure: 


typedef struct { 
WidgetList children; 
Cardinal num_children; 
Cardinal num_slots; 
XtOrderProc insert _position; 
} CompositePart; 


The default values are filled in by the Composite resource list and the Composite initialize 
procedure. The default values for the CompositePart data structure are: 


[Feld [Betautvatue 
[num-chichen [0 
[mums foi 


Related Information 
The CompositeClassPart data structure. 







ConstraintClassPart Data Structure 


In addition to the Composite class fields, Constraint widgets have the following class 
fields: 


typedef struct { 
XtResourceList resources; 
Cardinal num_resources; 
Cardinal constraint_size; 
XtInitProc initialize; 
XtWidgetProc destroy; 
XtSetValuesFunc set_values; 
caddr_t extension; 

} ConstraintClassPart; 


Related Information 
The ConstraintPart data structure. 


ConstraintPart Data Structure 


In addition to the CompositePart fields, Constraint widgets have the following fields 
defined in the ConstraintPart data structure: 


typedef struct { int empty; } ConstraintPart; 


Related Information 
The ConstraintClassPart data structure. 
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-ArgList Data Structure 


typedef something ArgList; 


typedef struct { 
String name; 
ArgList value; 

} Arg, *ArgList; 


The ArgList data structure is a pointer to the Arg data structure. The ArgList data type is a 
C language type which is large enough to contain the following: caddr_t, char’, long, int*, 
or a pointer to a function. 


Many of the Intrinsics routines need to receive pairs of resource names and values, called 
an argument list. These are passed as an ArgList structure. 


name Specifies the name of the resource. 


value Contains the resource value if the size of the resource is less than or equal 
ArgListto the size of an ArgList structure. Otherwise, the value field is a 
pointer to the resource value. 


Related Information 
The XtMergeArgLists subroutine, XtSetArg subroutine. 


XtinitProc Data Type 


typedef void (*XtInitProc) (Widget, Widget) 
Widget request; 
Widget new; 


The XtinitProc procedure is the initialize procedure (the procedure specified in the initialize 
field of a widget class) pointer type for a widget class. 


An initialization procedure performs the following: 


e Allocates space for and copies any resources that are referenced by address. For 
example, if a widget has a field that is a String, it cannot depend on the characters at that 
address remaining constant but must dynamically allocate space for the string and copy it 
to the new space. (note that you should not allocate space for or copy callback lists.) 


e Computes values for unspecified resource fields. for example, if the width and height are 
0, the widget should compute an appropriate width and height based on ohter resources. 
This is the only time that a widget should ever directly assign its own width and height. 


e Computes values for uninitialized nonresource fields that are derived from resource fields. 
For example, graphics contexts (GCs) that the widget uses are derived from resources 
like background, foreground, and font. 


An initialization procedure can also check certain fields for internal consistancy. For 
example, it makes no sense to specify a color map for a depth that does not support that 
color map. 


A subclass compares the difference between a specified size and a size computed by a 
superclass by checking the request and new fields in the XtInitProc data type. 


request Specifies the widget with resource values as requested by the argument list, 
the resource database, and the widget defaults. 
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new Specifies a widget with the new values, both resource and nonresource, that 
are allowed. A subclass initialize procedure compares the values to resolve 
potential conflicts. 





XtArgsProc Data Type 


typedef void (*XtArgsProc) (Widget, ArgList, Cardinal*); 
Widget w; 
ArgList args; 
Cardinal *num_args; 


Description 
The XtArgsProc specifies the interface for the initialize_hook and get_values_hook 
procedures of a widget. 


If the XtArgsProc procedure is not the value of NULL, it is called immediately after the 
corresponding initialize procedure or in place of it, if the initialize procedure is the value of 


NULL.. 
Parameters 
Ww Specifies the widget ID. 
args Specifies the argument list to override the resource defaults. 
num_args Specifies the number of arguments in the argument list. 





XtCallbackProc Data Type 


typedef void (*XtCallbackProc) (Widget, caddr_t, caddr_t); 
Widget w; 
caddr_t client_data; 
caddr_t call_data; 


The XtCalibackProc data type specifies the interface of a callback procedure to be used in 
callback lists. A client can register the callback and client-specific data (such as a pointer to 
additional information about the widget) in the client_data field. The client data should be the 
value of NULL if all necessary information is in the widget. 


The call_data field allows the client application to specify data about the callback. This 
parameter helps the client avoid using the XtGetValues subroutine or a widget-specific 
subroutine to retrieve data from the widget. For example, if the Scrollbar executes the 
thumbChanged callback list, the ca//_data field passes the new position of the thumb. 


Note: Do not use the call_data field for complex information. 


Fields 


w Specifies the widget ID for which the callback is registered. 


client_data Specifies the data that should be passed to the client when the widget 
executes the client’s callback. If all necessary information is in the widget, 
this parameter has the value of Null. 


call_data Specifies any callback data that should be passed to the client when the 
widget executes the client's callback. 
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Related Information 
The XtCallbackList data structure. 


The XtCreateWidget subroutine, XtGetValues subroutine. 





XtCallbackList Data Structure 


typedef struct { 
XtCallbackProc callback; 
caddr_t closure; 

} XtCallbackRec, *XtCallbackList; 


The XtCallbackList structure specifies the address of a null-terminated list, and is used to 
pass callback information to the XtCreateWidget subroutine, XtSetValues subroutine, or 
XtGetValues subroutine. 


callback Specifies a pointer to the callback procedure. 


closure Specifies any client data to be passed to the callback procedure. 


Related Information 
The XtCreateWidget subroutine, XtGetValues subroutine, XtSetValues subroutine. 


XtWidgetProc Data Type 


typedef void (*XtWidgetProc) (Widget) 
Widget w; 


The XtWidgetProc data type specifies the interface for a user defined destroy, resize, 
change_managed, insert_child, or delete_child procedures of a widget. These procedures 
are stored in the following fields of a widget: 


destroy Destroy procedures are called in subclass-to-superclass order. Therefore, a 
widget’s destroy procedure should only deallocate storage specific to the 
subclass and should not bother with the storage allocated by any of its 
superclasses. The destroy procedure should only deallocate resources that 
have been explicitly created by the subclass. Any resource that was 
obtained from the resource database or was passed in with an argument list 
was not created by the widget and, therefore, should not be destroyed by it. 
lf a widget does not need to deallocate any storage, the destroy procedure 
entry in its widget class record can be the value of NULL. 


resize If the composite widget wishes to change the size or border width of any of 
its children, it calls the XtResizeWidget subroutine, which first updates the 
Core fields and then calls the XConfigureWindow subroutine if the widget 
is realized. 


A child can be resized by its parent at any time. Widgets usually need to know when they 
have changed size so that they can lay out their displayed data again to match the new size. 
When a parent resizes a child, it calls XtResizeWidget, which updates the geometry fields 
in the widget., configures the window if the widget is realized, and calls the child’s resize 
procedure to notify the child. The resize procedure pointer is of type XtWidgetProc. 


If a class need not recalculate anything when a widget is resized, it can specify NULL for the 
resize field in its class record. This is an unusual case and should occur only for widgets with 
very trivial display semantics. The resize procedure takes a widget as its only argument. The 
x, y, width, height and border_width fields of the widget contain new values. The resize 
procedure should recalculate the layout of internal data as needed. (For example, a 
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centered Label in a window that changes size should recalculate the starting position of the 
text.) The widget must obey resize as a command and must not treat it as a request. A 
widget must not issue an XtMakeGeometryRequest or XtMakeResizeRequest call from its 
resize procedure. 


change_managed Child widgets are added to and removed from the managed set by 
using the XtManageChild, XtManageChildren, 
XtUnmanageChild, and XtUnmanageChildren subroutines, which 
notify the parent to recalculate the physical layout of its children by 
calling the parent’s change_managed procedure. The 
XtCreateManagedWidget convenience subroutine calls the 
XtCreateWidget and XtManageChild subroutines on the result. 


insert_child To add a child to the parent's list of children, the XtCreateWidget 
subroutine calls the parent’s class routine insert_child. 


Most composite widgets inherit their superclass’ operation. The insert_child routine calls the 
insert_position procedure and inserts the child at the specified position. 


Some composite widgets define their own insert_child routine so that they can order their 
children in some convenient way, create companion controller widgets for a new widget, or 
limit the number or type of their children widgets. 


If there is not enough room to insert a new child in the children array (the num_children field 
of the widget == the num_siots field), the insert_child procedure must first reallocate the 
array and update the num_siots field of the widget. The insert_child procedure then places 
the child wherever it wants and increments the num_children field of the widget. 


delete_child Most widgets inherit the delete_child procedure from their 
superclass. Composite widgets that create companion widgets 
define their own delete_child procedure to remove these companion 
widgets. To remove the child from the parent's children array, the 
XtDestroyWidget function eventually causes a call to the 
composite parent’s delete_child procedure. 


The XtWidgetProc data type contains the following field: 
w Specifies the widget. 


Related Information 
The CompositeClassPart data structure, ConstraintClassPart data structure. 


The XFreeGC subroutine, XFreePixmap subroutine, 

XtAddEventHandlersubroutine, XtAppAddTimeout subroutine, XtCalloc subroutine, XtDe 
stroyWidget subroutine, XtFree subroutine, XtGetGC subroutine, XtMalloc subroutine, 
XtRemoveEventHandler subroutine, XtRemoveTimeout subroutine, XtResizeWidget 
subroutine. 





XtOrderProc Data Type 


typedef Cardinal (*XtOrderProc) (Widget); 
Widget w; 


The XtOrderProc data type is the interface definition for the insert_position procedure in a 
composite widget instance. This procedure is useful when composite widgets need a specific 
order for their children widgets; it determines where a new child should go in the children list 
of the widget. This procedure is called from the insert_child procedure of the widget class. 
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The return value of the insert_position procedure indicates how many children should go 
before the widget 


w Specifies the widget. 


Return Values 
— 0 indicates that the widget should go before all other children. 


num_children \ndicates that the widget should go after all other children. 


Related Information 
The CompositePart data structure. 
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Enhanced X-Windows ShellClassRec Data Structure 


typedef struct _ShellClassRec { 
CoreClassPart core_class; 
CompositeClassPart composite_class; 
ShellClassPart shell_class; 

} ShellClassRec; 


Related Information 
The ShellPart data structure. 
The ShellWidget data structure. 


OverrideShellClassRec Data Structure 


typedef struct OverrideShellClassRec { 
CoreClassPart core class; 
CompositeClassPart composite_class; 
ShellClassPart shell class; 
OverrideShellClassPart override_shell_class; 
} OverrideShellClassRec; 


Related Information 
The OverrideShellPart data structure. 
The OverrideShellWidget data structure. 


WMShellClassRec Data Structure 


typedef struct _WMShellClassRec { 
CoreClassPart core_class; 
CompositeClassPart composite class; 
ShellClassPart shell class; 
WMShellClassPart wm_shell_class; 

} WMShel1lClassRec; 


Related Information 
The WMShellPart data structure. 
The WMShellWidget data structure. 


VendorShellClassRec Data Structure 


typedef struct _VendorShellClassRec { 
CoreClassPart core_class; 
CompositeClassPart composite_class; 
ShellClassPart shell class; 
WMShellClassPart wm_shell_ class; 
VendorShellClassPart vendor_shell_class; 
} VendorShelliClassRec; 


Related Information 
The VendorShellPart data structure. 
The VendorShellWidget data structure. 
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TransientShellClassRec Data Structure 


typedef struct TransientShellClassRec { 
CoreClassPart core class; 
CompositeClassPart composite class; 
ShellClassPart shell class; 
WMShellClassPart wm_shell_ class; 
VendorShellClassPart vendor_shell_class; 
TransientShellClassPart transient_shell_ class; 
} TransientShellClassRec; 


Related Information 
The TransientShellPart data structure. 
The TransientShellWidget data structure. 


TopLevelShellClassRec Data Structure 


typedef struct TopLevelShellClassRec { 
CoreClassPart core class; 
CompositeClassPart composite class; 
ShellClassPart shell class; 
WMShellClassPart wm_shell class; 
VendorShellClassPart vendor_shell _ class; 
TopLevelShellClassPart top _level_shell_ class; 
} TopLevelShellClassRec; 


Related Information 
The TopLevelSheliPart data structure. 
The TopLevelShellWidget data structure. 


ApplicationShellClassRec Data Structure 


typedef struct ApplicationShellClassRec { 
CoreClassPart core class; 
CompositeClassPart composite _class; 
ShellClassPart shell_class; 
WMShellClassPart wm_shell_ class; 
VendorShellClassPart vendor_shell_ class; 
TopLevelShellClassPart top_level_shell_ class; 
ApplicationShellClassPart application_shell_class; 
} ApplicationShellClassRec; 


Related Information 


The ApplicationShellPart data structure. 
The ApplicationShellWidget data structure. 
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ShellPart Data Structure 


typedef struct { 
String geometry; 


XtCreatePopupChildProc create_popup_child_proc; 


XtGrabKind grab_kind; 
Boolean spring loaded; 


Boolean popped_up; 


Boolean allow_shell resize; 
Boolean client_specified; 


Boolean save_under; 


Boolean override redirect; 
XtCallbackList popup callback; 
XtCallbackList popdown_callback; 


} ShellPart; 
allow_shell_resize 


client_specified 


create_popup_child_proc 


geometry 


grab_kind 


override_redirect 


popdown_callback 


popped_up 
popup_callback 


save_under 


spring_loaded 
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This field controls whether or not the widget contained 
by the shell is allowed to resize itself. If the value of 
the field is False, geometry requests return the value 
XtGeometryNo. The default value for the 
allow_shell_resize field is False. 


By default, the client_specified field is used internally. 


The procedure defined by this field is called by the 
XtPopup subroutine. The default value for the 
create_popup_child_proc field is NULL. 


Specifies size and position and is usually done only 
from a command line or a defaults file. The default 
value for the geometry field is NULL. 


By default, the grab_kind field is used internally. 


Setting the override_redirect field determines whether 
or not the shell window is visible to the window 
manager. If it is the value of True, the window is 
immediately mapped without the intervention of the 
manager. The default value for the override_redirect 
field is True for the OverrideShell, and False 
otherwise. 


This field is called during the XtPopdown subroutine. 
The default value for the popdown_caliback field is 
NULL. . 


By default, the popped_up field is used internally. 


This is called during the XtPopup subroutine. The 
default value for the popup_callback field is NULL. 


Setting the save_under field instructs the server to 
attempt to save the contents of windows obscured by 
the shell when it is mapped and to restore its contents 
automaticlly later. It can be useful for pop-up menus. 
The default value for the save_under field is True for 
the OverrideShell and TransientShell widget 
classes, and False otherwise. 


By default, the spring_loaded field is used internally. 


Related Information 
The ShellClassRec data structure. 
The ShellWidget data structure. 


OverrideShellPart Data Structure 


typedef struct { int empty; } OverrideShellPart; 


Related Information 
The OverrideSheliClassRec data structure. 
The OverrideSheliWidget data structure. 


WMShellPart Data Structure 


typedef struct { 
String title; 
int wm_timeout; 
Boolean wait for_wm; 
Boolean transient; 
XSizeHints size hints; 
XWMHints wm_hints; 

} WMShellPart; 


The common shell fields and their default values in the WMShell widget class and its 
subclasses are: 


size_hints Specifies resources for sizing the window. This can include the 
following: 

max_height The default value for the max_height field is None. 

max_width The default value for the max_width field is None. 

min_height The default value for the min_height field is None. 

min_width The default value for the min_width field is None. 

height_inc The default value for the height_inc field is None. 

width_ince The default value for the width_inc field is None. 

title This value is a string displayed by the window manager. The 
default value for the title field is the icon name if one is specified. 
Otherwise it is the name of the application. | 

transient The default value for the transient field is True for the 
TransientShell widget class, and False otherwise. 

wait_for_wm The default value for the wajit_for_wm field is True. This field is 
set to False when a shell does not receive confirmation of a 
geometry request to the window manager within the time defined 
for the wm_timeout field. When the field is the value of False, the 
sheli does not wait for confirmation but relies on asynchronous 
notification. 

wm_hints Specifies resources for window manager hints. This can include 


min_aspect_x 


the following: 
The default value for the min_aspect_x field is None. 
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min_aspect_y 
max_aspect_x 
max_aspect_y 
input 
initial_state 
icon_pixmap 
icon_window 
icon_x 

icon_y 
icon_mask 


window_group 


The default value for the min_aspect_y field is None. 
The default value for the max_aspect_x field is None. 
The default value for the max_aspect_y field is None. 
The default value for the input field is False. 

The default value for the initial_state field is normal. 
The default value for the icon_pixmap field is None. 
The default value for the icon_window field is None. 
The default value for the icon_x field is None. 

The default value for the icon_y field is None. 

The default value for the icon_mask field is None. 


The default value for the window_group field is None. 


Limits the amount of time a shell is to wait for confirmation of a 
geometry request to the window manager. If no confirmation 
comes before the defined timeout, the shell assumes the window 
manager is not functioning properly and sets the wait_for_wm 
field to the value of False. The default value for the wm_timeout 
field is five seconds. 


wm_timeout 


Related Information 
The WMShellClassRec data structure. 
The WMShellWidget data structure. 


VendorShellPart Data Structure 


typedef struct { 
int vendor_specific; 
} VendorShellPart; 


Related Information 
The VendorShellClassRec data structure. 
The VendorShellWidget data structure. 


TransientShellPart Data Structure | 
typedef struct { int empty; } TransientShellPart; 
Related Information 


The TransientShellClassRec data structure. 
The TransientShellWidget data structure. 


TopLevelShelliPart Data Structure 


typedef struct { 
String icon_name; 
Boolean iconic; 

} TopLevelShellPart; 
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The common shell fields and their default values for the TopLevel shells are: 


icon_name The default value for icon_name is the name of the shell widget. 
| This field contains a string for display in the icon of the shell. 


iconic The default value for iconic is False. Setting this field to True is 
an alternative way to set the /nitialState resource to indicate that 
a shell is displayed initially as an icon. 


Related Information 
The TopLevelShellClassRec data structure. 
The TopLevelShellWidget data structure. 


ApplicationShellPart Data Structure 


typedef struct { 
char *class; 
XrmClass xrm_class; 
int argc; 
char **argv; 

} ApplicationShellPart; 


The common shell fields and their default values for Application shells are: 


argc This field is used to initialize the WM_COMMAND standard 
property. The default value for argc is 0 (zero). 
argv This field is used to initialize the WM_COMMAND standard 


property. The default value for argvis NULL. 


Related Information 
The ApplicationSheliClassRec data structure. 
The ApplicationShellWidget data structure. 


ShellWidget Data Structure 


typedef struct { 
CorePart core; 
CompositePart composite; 
ShellPart shell; 

} ShellRec, *ShellWidget; 


Related Information 
The ShellClassRec data structure. 
The SheilPart data structure. 


OverrideShellWidget Data Structure 


typedef struct { 
CorePart core; 
CompositePart composite; 
ShellPart shell; 
OverrideShellPart override; 
} OverrideShellRec, *OverrideShellWidget; 


Chapter 5. Enhanced X-Windows 5—225 


Related Information 
The OverrideShellClassRec data structure. 
The OverrideShellPart data structure. 


WMShellWidget Data Structure 


typedef struct { 
CorePart core; 
CompositePart composite; 
ShellPart shell; 
WMShellPart wm; 

} WMShellRec, *WMShellWidget; 


Related Information 
The WMShellClassRec data structure. 
The WMShellPart data structure. 


VendorShellWidget Data Structure 


typedef struct { 
CorePart core; 
CompositePart composite; 
ShellPart shell; 
WMShellPart wm; 
VendorShellPart vendor; 
} VendorShellRec, *VendorShellWidget; 


Related Information 
The VendorShellClassRec data structure. 
The VendorShellPart data structure. 


TransientShellWidget Data Structure 


typedef struct { 
CorePart core; 
CompositePart composite; 
ShellPart shell; 
WMShellPart wm; 
VendorShellPart vendor; 
TransientShellPart transient; 
} TransientShellRec, *TransientShellWidget; 


Related Information 
The TransientSheliClassRec data structure. 
The TransientShellPart data structure. 
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TopLevelShellWidget Data Structure 


typedef struct { 
CorePart core; 
CompositePart composite; 
ShellPart shell; 
WMShellPart wm; 
VendorShellPart vendor; 
TopLevelShellPart topLevel; 
} TopLevelShellRec, *TopLevelShellWidget; 


Related Information 
The TopLevelShelliClassRec data structure. 
The TopLevelShelilPart data structure. 


ApplicationShellWidget Data Structure 


typedef struct { 
CorePart core; 
CompositePart composite; 
ShellPart shell; 
WMShellPart wm; 
VendorShellPart vendor; 
TopLevelShellPart topLevel; 
ApplicationShellPart application; 
} ApplicationShellRec, *ApplicationShellWidget; 


Related Information 
The ApplicationShellClassRec data structure. 
The ApplicationShellPart data structure. 


XtWorkProc Data Type 


typedef Boolean(*XtWorkProc) (caddr_t) 
caddr_t client_data; 


The XtWorkProc data type specifies the interface definition for user defined idle-time 
work procedures. The user defined procedure must return the value of True if it is done 
(that is, the work is complete). 


client_data Specifies the client data generated when the work procedure was 
registered. : 


Related Information | 
The XtAppAddWorkProc subroutine. 
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XtExposeProc Data Type 
Syntax 


typedef void (*XtExposeProc) (Widget, XEvent *, Region) 
Widget w; 
XEvent *event; 
Region region; 


Description 
The XtExposeProc data type specifies the interface definition for user defined expose 
procedure in widget classes. The expose procedure redisplays a widget upon exposure 
(This redisplay is the responsibility of the widget.). If a widget has no display semantics, 
specify the value of NULL for its expose procedure. For example, many composite widgets 
serve as containers for their children only and have no expose procedure. 


Note: If the XtExposeProc procedure is the value of NULL, the XtRealizeWidget 
subroutine fills in the default bit gravity of NorthWestGravity before it calls the 
widget realize procedure. 


Fields 
event Specifies the exposure event that identifies the rectangle that requires 
redisplaying. This parameter contains the bounding box for the Region 
parameter, if the compress_exposure field of the widget is the value of True. 


region Specifies the union of all rectangles in this exposure sequence. This 
parameter is the value of NULL if the compress_ epoeue field of the 
widget is the value of False. 


Ww Specifies the ID of the widget instance that requires displaying. 


Related Information 
The XtRealizeWidget subroutine. 


XtEventHandler Data Type 


typedef void (*XtEventHandler) (Widget, caddr_t, XEvent*); 
Widget w; 
caddr_t client_data; 
XEvent *event; 


The XtEventHandler data type is the interface definition for user defined event handler 
procedures for widgets that must use event handlers explicitly. Most widgets use the 
translation manager, instead of using event handlers explicitly. 


client_data Specifies the client-specific information registered with the event handler. If 
the event handler is registered by the widget, this parameter is the value of 


NULL. 
event Specifies the triggering event. 
w Specifies the widget ID for which to handle events. 
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XtWidgetGeometry Data Structure 
The XtWidgetGeometry data structure is similar to a corresponding Xlib structure. 


typedef unsigned long XtGeometryMask; 


typedef struct { 
XtGeometryMask request_mode; 
Position x, y; 
Dimension width, height; 
Dimension border width; 
Widget sibling; 
int stack_mode; 

} XtWidgetGeometry; 


The following request_mode values are from the <X11/X.h> header file: 


#define CWX (1<<0) 
#define CWY (1<<1) 
#define CWWidth (1<<2) 
#define CWHeight (1<<3) 
#define CWBorderWidth (1<<4) 
#define CWSibling (1<<5) 
#define CWStackMode (1<<6) 


The Intrinsics also support the following value: 
#define XtCWQueryOnly (1<<7) 


The XtCWQueryOnly value indicates that the corresponding geometry request is only a 
query asking what would happen if this geometry request were made and that no widgets 
are actually changed. 


The XtMakeGeometryRequest subroutine (like the corresponding Xlib 
XConfigureWindow subroutine) uses request_mode to determine which fields in the 
XtWidgetGeometry structure you want to specify. 


The stack_mode values are defined in the <X11/X.h> header file: 


#define Above 0 
#define Below 1 
#define TopIf 2 
#define BottomIif 3 
#define Opposite 4 


The Intrinsics also support the following value: 
#define XtSMDontChange 5 


The XtSMDontChange value indicates that the widget requires its current stacking order 
preserved. 


Related Information 
The XtGeometryResult data structure. 
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XtGeometryResult Data Structure 
The return codes from geometry managers are: 


typedef enum XtGeometryResult { 
XtGeometryYes, 
XtGeometryNo, 
XtGeometryAlmost, 
XtGeometryDone, 

} XtGeometryResult; 


Related Information 
The XtWidgetGeometry data structure. 


XtGeometryHandler Data Type 


Syntax 
typedef XtGeometryResult(*XtGeometryHandler) (Widget, 
XtWidgetGeometry*, 
XtWidgetGeometry* ) 
Widget w; 
XtWidgetGeometry *request; 
XtWidgetGeometry *geometry_ return; 
Description 


The XtGeometryHandler data type specifies the interface definition for the 
geometry_manager procedure in a composite widget. A class can inherit the geometry 
manager of its superclass during class initialization. 


The same definition is also used for the query_geometry procedure in a widget. The 
query_geometry procedure: 


e Examines the bits set in the request->request_mode parameter. 
e Evaluates the preferred geometry of the widget. 


e Stores the result in the geometry_return parameter. It sets the bits in the 
geometry_return—>request_mode parameter to the corresponding geometry fields. 


e Generates the appropriate return value. 


A bit set to the value of 0 in the mask field of the request means that the child widget does 
not care about the value of the corresponding field. Then the geometry manager can change 
it as it wishes. A bit set to 1 means that the child wants that geometry element changed to 

~ the value in the corresponding field. 


If the geometry manager can satisfy all changes requested and if XtCWQueryOnlly is not 
specified, it updates the widget’s x, y, width, height, and border_width values appropriately. 
Then it returns XtGeometry Yes, and the value of the geometry_return argument is 
undefined. The widget’s window is moved and resized automatically by 
XtMakeGeometryRequest. 


Homogeneous composite widgets often find it convenient to treat the widget making the 
request the same as any other widget, possibly reconfiguring it as part of its layout process, 
unless XtCWQueryOnlly is specified. If it does this, it should return XtGeometryDone to 
inform XtMakeGeometryRequest that it does not need to do the configuration itself. 
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Fields 


Although XtMakeGeometryRequest resizes the widget’s window (if the geometry manager 
returns XtGeometry Yes), it does not call the widget class’s resize procedure. The 
requesting widget must perform whatever resizing calculations are needed explicitly. 


If the geometry manager chooses to disallow the request, the widget cannot change its 
geometry. The value of the geometry_return parameter is undefined, and the geometry 
manager returns XtGeometryNo. 


Sometimes the geometry manager cannot satisfy the request exactly, but may be able to 
satisfy a similar request. That is, it could satisfy only a subset of the requests or a lesser 
request. In such cases, the geometry manager fills in the geometry_return field with the 
actual changes it is willing to make, including an appropriate mask, and returns 
XtGeometryAlmost. If a bit in the geometry_return->request_mode is 0, the geometry 
manager does not change the corresponding value if the geometry_return field is used 
immediately in a new request. If a bit is 1, the geometry manager does change that element 
to the corresponding value in the geometry_return field. More bits may be set in the 
geometry_return field than in the original request if the geometry manager intends to change 
other fields should the child accept the compromise. 


When the XtGeometryAlmost value is returned, the widget must decide if the compromise 
suggested in the geometry_return field is acceptable. If it is, the widget must not change its 
geometry directly; rather, it must make another call to the XtMakeGeometryRequest 
subroutine. 


If the next geometry request from this child uses the geometry_return box filled in by an 
XtGeometryAlmost return and if there have been no intervening geometry requests on 
either its parent or any of its other children, the geometry manager must grant the request, if 
possible. That is, if the child asks immediately with the returned geometry, it should get an 
answer of XtGeometryYes. However, the user’s window manager may affect the final 
outcome. 


To return an XtGeometryYes value, the geometry manager frequently rearranges the 
position of other managed children by calling the XtMoveWidget subroutine. However, a few 
geometry managers may sometimes change the size of other managed children by calling 
the XtResizeWidget or the XtConfigureWidget subroutine. If XtCWQueryOnly is 

specified, the geometry manager must return how it would react to this geometry request 
without actually moving or resizing any widgets. 


Geometry managers must not assume that the request and geomeitry_return fields point to 
independent storage. The caller is permitted to use the same field for both, and the 
geometry manager must allocate its own temporary storage , if necessary. 


geometry_return Specifies the geometry request returned by the geometry manager. 
request Specifies the request for a geometry change. 
Ww Specifies the widget. 


Return Values 


XtGeometryAimost __ Indicates that at least one field in the PreferredReturn parameter is 
different from the corresponding field in the Intended parameter or if 
a bit is set in PreferredReturn parameter that is not set in the 
Intended parameter of the query_geometry procedure. 


XtGeometryNo Indicates that the preferred geometry is identical to the current 
geometry. 
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XtGeometryYes Indicates that the proposed geometry change is acceptable without 
modification. 


Related Information 
The XtQueryGeometry subroutine. 


XtResource Data Structure 
The declaration for the XtResource data structure is: 


typedef struct { 
String resource_name; 
String resource_class; 
String resource_type; 
Cardinal resource_size; 
Cardinal resource_offset; 
String default_type; 
caddr_t default address; 

} XtResource, *XtResourceList; 


The following list describes the content of each of these structure fields: 


resource_name Contains the name used by clients to access the field in the widget. This 
name starts with a lower-case letter. It is spelled almost the same as the 
field name, except that underscores (_) are deleted, and the next leter 
replaced by its uppercase counterpart. For example, the resource name 
for background_pixe/ is backgroundPixel. Widget header files typically 
contain a symbolic name for each resource name. All resource names, 
classes, and types used by the Intrinsics are in the <X11/String Defs.h> 
header file. The Intrinsics symbolic resource names begin with XtN and 
are followed by the string name; for example, XtNbackgroundPixel for 
backgroundPixel. 


resource_class A resource class has two functions: 


e Itisolates an application from different representations that widgets 
can use for a similar resource. 


e itlets an application specify values for several resources with a single 
name. A resource class should be chosen to span a group of closely 
related fields. 


For example, a widget can have several pixel resources, such as 
background, foreground, border, block cursor, mouse cursor, and so on. 
Typically, the background defaults to white and everything else defaults to 
black. The resource class for each of these resources in the resource list 
should be chosen so that it takes a minimal number of entries in the 
resource database to make background oftwhite and everything else 
darkblue: 


In this case, the background pixel should have a resource class of 
Background and ail the other pixel entries should have a resource class 
of Foreground. Then, the resource file needs just two lines to change all 
pixels to offwhite or darkblue: 


*Background: offwhite 
*Foreground: darkblue 
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resource_type 


resource_size 


resource_offset 


default_type 


Similarly, a widget may have several resource fonts, such as normal 
and bold, but all fonts should have the class Font. Changing all fonts 
requires one line in the default file: 


Font: Rom14.500 


Resource class names begin with a capitalized letter. This name is 
preceded by XtC (for example. XtCBackground). 


The physical representation type of the resource. This name begins 
with an uppercase letter and is spelled the same as the type name of 
the field. The resource type is used when resources are called to 
convert from the resource database format (usually String) or the 
default resource format (often String) to the desired physical 
representation. The Intrinsics define the following resource types: 


Resource Type Structure or Field Type 
XtRAcceleratorTable XtAccelerators 
XtRBoolean Boolean 
XtRBool Bool 
XtRCallback XtCalibackList 
XtRColor XColor 
XtRCursor Cursor 
XtRDimension Dimension 
XtRDisplay Display* 
XtRFile FILE* 
XtRFloat float 

XtRFont Font 
XtRFontStruct XFontStruct* 
XtRFunction (*)() 
XtRint int 

XtRPixel Pixel 
XtRPixmap Pixmap 
XtRPointer caddr_t 
XtRPosition Position 
XtRShort short 
XtRString char” 
XtRTranslationTable XtTranslations 
XtRUnsignedChar unsigned char 
XtRWidget Widget 


XtRWindow Window 


The size of the physical representation in bytes and should be 
specified as sizeof(type) so that the compiler can fill in the value. 


The offset in bytes of the field within the widget. Use the XtOffset 
macro to retrieve this value. 


The representation type of the default resource value. If default_type is 
different from resource_type and the default_type is needed, the 
resource manager invokes a conversion procedure from default_type 
to resource_type. Whenever possible, the default type should be 
identical to the resource type to minimize widget creation time. 
However, there are sometimes no values of the type that the 
application can easily specify. In this case, the value should be one 
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that the converter will work for, such as XtDefaultForeground for a 
pixel resource. 


default_address The address of the default resource value. The default is used if a 
resource is not specified in the argument list or in the resource 
database or if the conversion from the representation type stored in 
the resource database fails, which can happen for reasons (for 
example, a misspelled entry in a resource file). 


Two special representation types, XtRimmediate and XtRCallProc, can only be used as 
default resource types. XtRimmediate indicates that the value in the default_address field is 
the actual value of the resource, rather than the address of the value. The value must be in 
correct representation type for the resource. No conversion is possible since there is no 
source representation type. 


XtRCallProc indicates that the value in the default_address field is a procedure variable. 
This procedure is automatically invoked with the widget, resource_offset, and a pointer to 
the XrmValue data structure in which to store the result. 


Related Information 
The <X11/StringDefs.h> header file. 
The XrmValue data structure. 
The XtOffset macro. 





XtResourceDefaultProc Data Type 


The XrmValue data structure is of XtResourceDefaultProc data type, which has the 
following structure: 


typedef void eee eet ey ana eae int, XrmValue*) 
Widget widget; 
int offset; 
XrmValue *value; 


The XtResourceDefaultProc data type fills in the addr field of the value parameter with a 
pointer to the default data in its correct type. 


Note: The default_address field in the resource structure is declared as a caddr_t. On 
some machine architectures, this may be insufficient to hold procedure variables. 


When the default_address field of the XtResource data structure contains the resource type 
of XtRCallProc, the XtResourceDefaultProc data type is automatically called with the 
widget, the resource_offset field, and a pointer to the XrmValue data structure in which to 
store the result. 


The fields of the XtResourceDefaultProc data type are as follows: 


widget Specifies the widget whose resource is to be obtained. 
offset Specifies the offset of the field in the widget record. 


value Specifies the resource value to fill in. 


Related Information 
The XtResource data structure. 
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XrmValue Data Structure 


typedef struct { 
unsigned int size; 
caddr_t addr; 

} XrmValue, *XrmValuePtr; 


XtConverter Data Type 


typedef void (*XtConverter)(XrmValue*, Cardinal*, 
XrmValue*, XrmValue*); 
XrmValue *args; 
Cardinal *num_args; 
XrmValue *from; 
XrmValue *to; 


Description 
The Xtconverter data type specifies the interface definition for subroutines that convert 
resources from one type to another. 


Type converters do the following actions: 
e Check to see that the number of arguments passed is correct 
e Attempt the type conversion 


e If successful, return a pointer to the data in the to parameter; otherwise, call 
XtWarningMsg and return without modifying the to parameter. 


Most type converters just take the data described by the from parameter and return data by 
writing into the specified to parameter. A few need other information which is available in the 
specified argument list. A type converter can invoke another type converter, which allows 
differing sources that may convert into a common intermediate result to make maximum use 
of the type converter cache. 


The address written to—>addr can not be that of a lock variable because this is not valid after 
the converter returns. It should be a pointer to a static variable. 


The XtConverter data structure contains the following fields: 


args Specifies a list of additional XrmValue arguments to the converter if 
additional context is needed to perform the conversion. Otherwise, this field 
is the value of NULL. For example, the string—to—font converter needs the 
widget’s screen, or the string—to—pixel converter needs the widget’s screen 
and colormap. 


num_args Specifies the number of additional XrmValue arguments if additional context 
is needed. Otherwise, this field is the value of 0. 

from Specifies the value to convert. 

to Specifies the descriptor to use to return the converted value. 
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XtAddressMode Enumerated Type 


typdef enum { 


/*address mode parameter representation*/ 
XtAddress, /*address*/ 

XtBaseOffset, /*offset*/ 

XtImmediate, /*constant*/ 
XtResourceString, /*resource name string*/ 
XtResourceQuark, /*resource name quark*/ 


} XtAddressMode; 


Related Information 
The XtConvertArgRec data structure. 
The XtAppAddConverter subroutine. 


XtConvertArgRec Data Structure 


typedef struct { 
XtAddressMode address_ mode; 
caddr_t address_id; 
Cardinal size; 

} XtConvertArgRec, *XtConvertArgList; 


address_id Specifies the address of the resource. See the address_mode field 
definition for details. 


address_mode Specifies how the address_id field should be interpreted. This field may 
have the following values: . 


XtAddress Causes address_idto be interpreted as the address of the data. 
XtBaseOffset Causes address_id to be interpreted as the offset from the widget base. 
Xtimmediate Causes address_idto be interpreted as a constant. 


XtResourceString | 
Causes address_id to be interpreted as the name of a resource that is to be 
converted into an offset from a widget base. 


XtResourceQuark 
Is an internally compiled form of an XtResourceString. 


size Specifies the length of the data in bytes. 


Related Information 
The XtAddressMode enumerated type. 
The XtAppAddConverter subroutine. 


XtActionList Data Structure 


typedef struct XtActionsRec { 
String action_name; 
XtActionProc action_proc; 

} XtActionsRec, *XtActionList; 


action_name Specifies the name used in translation tables to access the procedure. 
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action_proc Specifies a procedure pointer of type XtActionProc, which points to a 
procedure that implements the functionality. 


Related Information 
The XtActionProc procedure pointer. 


XtActionProc Procedure Pointer 


typedef void (*XtActionProc) (Widget, XEvent*, 
String*, Cardinal*); 
Widget w; 
XEvent *event; 
String *params; 
Cardinal *num_params; 


The XtActionProc procedure pointer specifies the interface definition for action procedures. 
All widget class records contain an action table. In addition, an application can register its 
own action tables with the translation manager so that the translation tables it provides to 
widget instances can access application functionality. 


Ww Specifies the widget that caused the action to be called. 


event Specifies the event that caused the action to be called. If the action is called 
after a sequence of events, then the last event in the sequence is used. 


params Specifies a pointer to the list of strings that were specified in the translation 
table as arguments to the action. 


num_params Specifies the number of arguments specified in the translation table. 


Related Information 
The XtActionList data structure. 


The XtAppAddActions subroutine. 


XtKeyProc Data Type 


The translation manager provides support for automatically translating key codes in 
incoming key events into KeySyms. The XtKeyProc data type provides the interface 
definition for Keycode to KeySym translators. 


typedef void (*XtKeyProc) (Display*, KeyCode, Modifiers, 
Modifiers*, KeySym*); 
Display *display; 
KeyCode keycode; 
Modifiers modifiers; 
Modifiers *modifiers return; 
KeySym *keysym_ return; 


The XtKeyProc data type takes a Keycode and modifiers and produces a KeySym. Fora 
given key translator subroutine, the modifiers_return parameter will be a constant that 
indicates the subset of all modifiers that are examined by the key translator. Applications 
should register this key converter with the XtSetKeyTranslator subroutine. 


The following fields are included in the XtKeyProc data type: 
display Specifies the display that the key code is from. 
keycode Specifies the key code to translate. 
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modifiers Specifies the modifiers to the key code. 


modifiers_return 
Returns a mask that indicates the subset of all modifiers are examined by 
the key translator. 


keysym_return Returns the resulting KeySym. 


Related Information 
The XtCaseProc data type. 


The XtRegisterCaseConverter sburoutine, XtSetKeyTranslator subroutine, 
XtTranslateKeycode subroutine. 


XtCaseProc Data Type 


typedef void (*XtCaseProc) (KeySym*, KeySym*, KeySym*); 
KeySym *keysym; 
KeySym *lower_ return; 
KeySym *upper return; 


The XtCaseProc data type specifies the interface for a case converter procedure. It allows 
capitalization of nonstandard key symbols. A case conversion routine should be registered 
with the Intrinsics library by using the XtRegisterCaseConverter subroutine. The 
_XtConvertCase subroutine calls the appropriate user defined XtCaseProc Procedure. lf 
there is no case distinction, the user defined XtCaseProc Procedure should store the key 
symbols in both return values. 


keysym Specifies the key symbol for the conversion. 
lower_return Specifies the lowercase equivalent for the key symbol. 
upper_return Specifies the uppercase equivalent for the key symbol. 


Related Information 
The XtConvertCase subroutine, XtRegisterCaseConverter subroutine. 


XtAcceptFocusProc Data Type 


typedef Boolean (*XtAcceptFocusProc) (Widget, Time); 
Widget w; 
Time *time; 


The XtAcceptFocusProc data type defines the user written interface for the accept_focus 
procedure. To allow outside agents to cause a widget to get the input focus, every widget 
exports an accept_focus procedure. The widget returns even when it does not accept the 
focus, so that the parent can give the focus to another widget. 


Widgets that must know when they lose the input focus should use the Xlib library focus 


notification mechanism explicitly by specifying translations for the FocusIn and FocusOut 
events. 


Widgets that do not want the input focus should set the accept_focus procedure pointer to 
the value of NULL. 


Widgets that need the input focus can call the XSetInputFocus subroutine explicitly. 


time Specifies the X time of the event causing the accept_focus procedure. 
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w Specifies the widget ID. 


Related Information 
The XtCallAcceptFocus subroutine, XSetinputFocus subroutine, XtSetKeyboardFocus 
subroutine. 





XtAlmostProc Data Type 


typedef void (*XtAlmostProc) (Widget, Widget, XtWidgetGeometry*, 
XtWidgetGeometry* ); 
Widget w; 
Widget new_widget_return; 
XtWidgetGeometry *request; 
XTWidgetGeometry *reply; 


The XtAlmostProc data type defines the interface for the set_values_almost field of a 
widget. This field is a procedure pointer. Most classes inherit this operation from their 
superclass by specifying XtInheritSetValuesAlmost in the class initialization. The core 
set_values_almost field accepts the compromise suggest. 


The set_values_almost procedure is called when the geometry manager cannot satisfy a 
client’s request to set the window geometry with the XtSetValues subroutine. The geometry 
manager returns the XtGeometryAlmost value with a compromise geometry. 


The set_values_almost procedure takes the original geometry and the compromise | 
geometry and determines an acceptable compromise, which may be the current compromise 
or a different compromise. It returns the results in the new_widget_return field, which is then 

sent to the geometry manager for another try. 


new_widget_return Specifies the new widget which will store the geometry changes. 





reply Specifies the compromise geometry returned by the geometry 
manager. 

request Specifies the original geometry request sent to the geometry 
manager. 

w Specifies the widget ID on which the geometry change is requested. 

XtArgsFunc Data Type 
typedef Boolean (*XtArgsFunc) (Widget, Arglist, Cardinal*); 
Widget w; 


ArgList args; 
Cardinal *num_args; 


The XtArgsFunc specifies the interface for the set_ values_hook procedure pointer of a 
widget. Widgets with a subpart can set the resource values with the XtSetValues subroutine 
and a set_values_hook procedure. 


args Specifies the argument list for the XtCreateWidget subroutine. 

num_args Specifies the number of arguments in the argument list. 

w Specifies the widget ID whose non-widget resource values are to be 
changed. 
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Related Information 
The CoreClassPart data structure. 


The XtCreateWidget subroutine, XtSetValues subroutine. 





XtPopdownlID Data Structure 


typedef struct { 
Widget shell widget; 
Widget enable widget; 
} XtPopdownIDRec, *XtPopdownID; 


The XtPopdownID structure identifies the widgets involved in the XtCallbackPopdown 
subroutine. The address of an XtPopdownlID structure is passed as the client data to the 
XtCallbackPopdown subroutine. 


enable_widget Specifies the widget used to pop the (pop-up) shell. 
shell_widget Specifies the pop-up sheil to be popped down. 


Related Information 
The XtCallbackPopdown subroutine, XtSetSensitive subroutine. 


XtConvertSelectionProc Data Type 


typedef Boolean (*XtConvertSelectionProc) (Widget, Atom*, Atom*, 
Atom*, caddr_t*, unsigned long*, int*); 
Widget w; 
Atom *selection; 
Atom *target; 
Atom *type return; 
caddr_t *value_return; 
unsigned long *length_return; 
int *format_return; 


The XtConvertSelectionProc data type is the interface definition for user defined 
procedures that get the value of a selection as a given type from the current selection owner. 


Each XtConvertSelectionProc data type should respond to the target value TARGETS by 
returning a value containing the list of the targets that will be used for the selection 
conversion. 


format_return Specifies a pointer into which the size (in bits) of the data elements of the 
selection value is to be stored. 


length_return Specifies a pointer into which the number of elements in the Va/ueReturn 
parameter is to be stored. 


selection _— Specifies the atom that describes the type of selection requested. (For 
example, XA_PRIMARY or XA_SECONDARY.) 

target Specifies the type of the selection requested, for example, a filename, text, 
or a window. 


type_return Specifies a pointer to an atom that will store the converted value of the 


selection. For example, a filename or text could specify XA_STRING as the 
value for this parameter. 
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value_return Specifies a pointer into which a pointer to the converted value of the 
selection is stored. The selection owner is responsible for allocating this 
storage. 


If the selection owner provided an XtSelectionDoneProc procedure for the selection, the 
storage is owned by the selection owner. Otherwise, the storage is owned by the Intrinsics 
selection mechanism. 


w Specifies the ID of the widget that currently owns the selection. 


Return Values 


False Indicates that the conversion did not take place. The values of the return 
parameters are undefined. 


True Indicates that the selection owner successfully converted the selection to 
the target type. 


Related Information 
The XtLoseSelectionProc data type, XtSelectionDoneProc data type, 
XtSelectionCallbackProc data type. 


The XtDisownSelection subroutine, XtGetSelectionValue subroutine, 
XtGetSelectionValues subroutine, XtOwnSelection subroutine. 


XtLoseSelectionProc Data Type 


typedef void (*XtLoseSelectionProc) (Widget, Atom*); 
Widget w; 
Atom* selection; 


The XtLoseSelectionProc data type specifies the interface definition for user defined 
procedures that are called by the Intrinsics selection mechanism to inform the specified 
widget that it has lost ownership of the specified selection. The user defined procedures do 
not initiate the loss of the selection ownership. 


selection Specifies the atom that describes the selection type. 


w Specifies the widget that has lost selection ownership. 


Related Information | 
The XtConvertSelectionProc data type, XtSelectionCalibackProc data type, 
XtSelectionDoneProc data type. 


The XtOwnSelection subroutine. 


XtSelectionCallbackProc Data Type 


typedef void (*XtSelectionCallbackProc) (Widget, caddr_t, Atom*, 
Atom*, caddr_t, unsigned long*, int*); 
Widget w; 
caddr_t client_data; 
Atom* selection; 
Atom* type; 
caddr_t value; 
unsigned long* length; 
int* format; 
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The XtSelectionCallbackProc data type specifies the interface for the user defined 
procedures that are called by the Intrinsics selection mechanism to deliver the requested 
selection to the requester. 


An XT_CONVERT_FAIL atom specified in the Type parameter, upon return of the user 
defined procedure, indicates that the selection conversion failed because the selection 
owner did not respond within the Intrinsics selection time—out interval. 


Parameters 

client_data Specifies a value passed in by the widget when the selection was 
requested. 

format Specifies the size in bits of the data elements of value. 

length Specifies the number of elements in value. 

selection Specifies the type of selection that was requested. 

type Specifies the type used to represent the selection value (for example, 
XA_STRING). 

value Specifies a pointer to the selection value. 


The requesting client owns the storage allocated for this parameter. Use the XtFree 
subroutine to de~allocate the storage space when this routine completes. 


w Specifies the widget that requested the selection value. 


Related Information 
The XtConvertSelectionProc data type, XtLoseSelectionProc data type, 
XtSelectionDoneProc data type. 


The XtFree subroutine, XtGetSelectionValue subroutine, XtGetSelectionValues 
subroutine. 


XtSelectionDoneProc Data Type 


typedef void (*XtSelectionDoneProc) (Widget, Atom*, Atom*); 
Widget w; 
Atom* selection; 
Atom* target; 


The XtSelectionDoneProc data type specifies the interface definition for user defined 
procedures that are called by the Intrinsics selection mechanism to inform the selection 
owner when a selection requester has retrieved a selection value successfully. 


Once the selection owner registers an XtSelectionDoneProc, the procedure will be called 
once for each conversion that it performs. This procedure is called after the converted value 
has been transferred successfully to the requester. 


The selection owner that registers an XtSelectionDoneProc also owns the storage 
containing the converted selection value. 


selection Specifies the atom that describes the selection type that was converted. 
target Specifies the target type to which the conversion was done. 
w Specifies the ID of the widget that owns the converted selection. 
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Related Information | 
The XtConvertSelectionProc data type, XtLoseSelectionProc data type, 
XtSelectionCallbackProc data type. 


XtErrorHandler Data Type 


typedef void (*XtErrorHandler) (String); 
String message; 


The XtErrorHandler data type specifies the interface definition for the low-level error and 
warning handler procedure. The error handler should display the specified message string in 
an appropriate manner. 


message Specifies the error message. 


Related Information 
The XtAppSetErrorHandler subroutine, XtAppSetWarningHandler subroutine. 


XtErrorMsgHandler Data Type 


typedef void (*XtErrorMsgHandler)(String, String, String, 
String, String *, Cardinal *); 

String name; 

String type; 

String class; 

String defaultp; 

String * params; 

Cardinal* num_params; 


The XtErrorMsgHandler data type specifies the interface definition for high—level error and 
warning handler procedures. 


The standard printf notation is used to substitute the parameters into the message. 


class Specifies the resource class of the error message. 
defaultp Specifies a default message if an error database entry is not found. 
name Specifies the name that is concatenated with the specified type to form the 


resource name of the error message. The specified name can be a general 
error, such as invalidParameters or invalidWindow. 


num_params — Specifies the number of values in the parameter list. 

params Specifies a pointer to a list of values to be substituted in the message. 

type Specifies the type that is concatenated with the name to form the resource 
name of the error message. The specified type gives extra information. 


Related Information 
The XtAppSetErrorMsgHandler subroutine, XtAppSetWarningMsgHandler subroutine. 
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XtInputCallbackProc Data Type 


typedef void (*XtInputCallbackProc) (caddr_t, int*, XtInputId*); 
caddr_t client_data; 
int* source; 
XtInputId* id; 


The XtIlnputCalibackProc data type specifies the interface definition for callback 
procedures used when there are file events. 


client_data Specifies the client data registered for this procedure in the XtAppAddInput | 


subroutine. 

id Specifies the ID returned from the corresponding XtAppAddinput 
subroutine. 

source Specifies the source file descriptor generating the event. 


Related Information 
The XtAppAddinput subroutine, XtRemovelnput subroutine. 


XtProc Data Type 
typedef void (*XtProc)(); 


The XtProc data type specifies the interface definition for the class initialization procedure 
pointer type. Most class records can be initialized completely at compile time. In some 
cases, however, a class may need to register type converters or perform other sorts of 
one-time initialization. 


A widget class indicates that is has no class initialization procedure by specifying the value 
of NULL in its class_initialize field. 


Related Information 
The XtWidgetClassProc data type. 


XtWidgetClassProc Data Type 


typedef void (*XtWidgetClassProc) (WidgetClass) ; 
WidgetClass widget_class; 


The XtWidgetClassProc data type provides the interface definition for the user defined 
procedures that will be stored in the class_part_initialize procedure field of a widget. 


Widgets have class initializations will be called exactly once. Some classes need to perform 
additional initializations for fields in its part of the class record. These are performed not just 
for the particular class, but subclasses as well. 


For classes that do not define new class fields and do not need extra processing, the value 
of NULL should be specified in the class_part_initialize field of a widget class. 


widget_class Specifies the class of the widget. 


Related Information 
. The XtProc data type. 
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XtRealizeProc Data Type 


typedef void (*XtRealizeProc) (Widget, XtValueMask*, 
XSetWindowAttributes*); 
Widget w; 
XtValueMask *value_mask; 
XSetWindowAttributes *attributes; 


The XtRealizeProc data type specifies the interface definition for the user defined realize 
procedure in a widget class. 


The generic XtRealizeWidget subroutine fills in a mask and a éorresponding 
XSetWindowaAttributes data structure. It sets the following fields based on information in 
the Core structure: 


e The background_pixmap field (or the background_pixel field if the background_pixmap 
field is NULL) is filled in from the corresponding field. 


e The border_pixmap field (or the border_pixel field if the border_pixmap field is NULL) is 
filled in from the corresponding field. 


e The event_mask field is filled in based on the event handlers registered, the event 
translations specified, whether the expose field is non-NULL, and whether the 
visible_interest field is True. 


e The bit_gravity field is set to NorthWestGravity if the expose field is NULL. 


e The do_not_propagate_mask field is set to propagate all pointer and keyboard events up 
the window tree. A composite widget can implement functionality caused by an event 
anywhere inside it (including on top of children widgets) as long as children do not specify 
a translation for the event. 


All other fields in attributes (and the corresponding bits in value_mask) can be set by the 
realize procedure. 


Note that because the realize procedure is not a chained operation, the widget class realize 
procedure must update the XSetWindowaAtiributes structure with all the appropriate fields 
from non-Core superciasses. 


A widget class can inherit its realize procedure from its superclass during class initialization. 
The realize procedure defined for Core calls the XtCreateWindow subroutine with the 
passed ValueMask and Attributes parameters and with the WindowClass and VisualPtr 
parameters set to CopyFromParent. Both CompositeWidgetClass and 
ConstraintWidgetClass inherit this realize procedure, and most new widget subclasses can 
do the same. 


The most common noninherited realize procedures set the bit_gravity in the mask and the 
attributes to the appropriate value and then create the window. For example, depending on 
its justification, the bit_gravity field can be set to the value of WestGravity, CenterGravity, 
or EastGravity. Consequently, shrinking the widget just moves the bits appropriately, and no 
Expose event is needed for repainting. 


If the children of a composite widget should be realized in a particular order (typically to 
control the stacking order), that composit widget should call the XtRealizeWidget subroutine 
on its children in the appropriate order from within its own realize procedure. 


Widgets that have children and that are not a subclass of compositeWidgetClass are 
responsible for calling the XtRealizeWidget subroutine on their children, usually from within 
the realize procedure. 
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The XtRealizeProc data type contains the following fields: 
attributes Specifies the window attributes to use in the XCreateWindow subroutine. 
value_mask — Specifies the fields from the attributes structure to use. 
w Specifies the ID of the widget. 
Related Information 
The XSetWindowdAttributes data structure. 
The XtCreateWindow subroutine, XtRealizeWidget subroutine. 





XtSetValuesFunc Data Type 


typedef Boolean (*XtSetValuesFunc) (Widget, Widget, Widget); 
Widget current; 
Widget request; 
Widget new; 


The XtSetValuesFunc data type specifies the inderface definition for the user defined 
procedure in the set_values field of a widget class. This procedure should recompute any 
field derived from resources that are changed. If no recomputation is necessary and if none 
of the resources specific to a subclass require the window to be redisplayed when their 
values are changed, you can specify the value of NULL for the set_values field in the class 
record. 


Like the initialize field, the set_va/ues field mostly deals with the fields defined in the 
subclass, but it has to resolve conflicts with its superclass, especially conflicts over width 
and height. Sometimes it is necessary for a subclass to overwrite values ee in by its 
superclass, particularly in the case of size calculations. 


The new and request parameters provide information for a subclass to determine the 
difference between a specified size and a size computed by its superclass. The request 
parameter is the widget as originally requested. The new parameter starts with the values of 
the request parameter, but has been modified by all superclass set_values fields called so 
far. A widget does not need to refer to the request parameter unless it must resolve conflicts 
between the widget in the current parameter and the widget in the new parameter. Any 
changes, including geometry changes, that the widget needs to make should be made to the 
widget specified in the new parameter. 


The set_values field must return a Boolean value that indicates if the widget needs to be 
redisplayed. A change in the geometry fields alone does not require the set_va/ues field to 
return the value of True; the X Server will eventually generate an Expose evert, if 
necessary. After calling all the set_values fields, the XtSetValues subroutine forces a 
redisplay by calling the XClearArea subroutine if any of the set_va/ues procedures returned 
the value of True. Therefore, a set_values field should not do its own redisplaying. 


The set_values field should not do any work in response to changes in geometry. A widget 
should do any geometry—related work in its Resize procedure. 


It is permissible to call XtSetValues before a widget is realized. Therefore, the set_va/ues 
field must not assume that the widget is realized. 


current Specifies a copy of the widget as it was before the XtSetValues subroutine 
was Called. 
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request Specifies a copy of the widget with all values changed as specified in the 


XtSetValues subroutine before any class set_values fields have been 
called. 


new Specifies the widget with the new values that are actually allowed. 


Related Information 
The XClearArea subroutine, XtSetValues subroutine. 





XtStringProc Data Type 


typedef void (*XtStringProc) (Widget, String) 
Widget w; 
String* string; 


The XtStringProc data type specifies the interface definition for the user defined procedures 


stored in the display_accelerator field of a widget. Accelerators can be specified in default 
files, and the string representation is the same as for a translation table. 


However, the interpretation of the #augment and #override directives apply to what will 
happen when the accelerator is installed, that is, whether or not the accelerator translations 
will override the translations in the destination widget. The default is #augment, which 
means that the accelerator translations have lower priority than the destination translations. 
The #replace directive is ignored for accelerator tables. 


string Specifies the string representation of the accelerators for this widget. 

w Specifies the ID of the widget that the accelerators are installed on. 
Related Information 

The CoreClassPart data structure. 


The XtParseAcceleratorTable subroutine, XtinstallAccelerators subroutine, 
XtIinstallAllAccelerators subroutine. 


XtTimerCalibackProc Procedure 


typedef void (*XtXtTimerCallbackProc) 
(caddr_ t, XtIntervalID*); 
caddr_t client data; 
XtIntervallId *id; 


The XtTimerCalibackProc procedure specifies the interface definition for the user defined 
procedures to be used when time-outs expire. 


client_data Specifies the client data that was registered for this procedure in the 
XtAppAddTimeOut subroutine. 


id Specifies the ID returned from the corresponding XtAppAddTimeOut 
subroutine. 


Related Information 
The XtAppAddTimeOut subroutine. 
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The X Protocol Overview 


The Core protocol is composed of requests, replies, errors and events. General information 
about protocol formats, syntax, types, errors, keyboard key assignments, pointers, and 
predefined atoms is followed by general information about connection setup, connection 
close, event generation, and flow control. 


Using the X Protocol Request Format 
Every protocol request contains an 8-bit major opcode and a 16-bit length field expressed in 
units of 4 bytes. A protocol request consists of a 4-byte header containing the major opcode, 
the length field, and a data byte, followed by zero or more additional bytes of data. Unused 
bytes in a protocol request are not required to be the value of 0. 


The length field in the protocol request defines the total length of the protocol request, 
including the header. The length in a request must equal the minimum length required to 
contain the request. If the specified length is smaller or larger than the required length, an 
error is generated. 


Extension requests typically have an additional minor opcode encoded in the spare data 
byte in the request header, but the placement and interpretation of this minor opcode, and all 
other fields in extension requests, are not defined by the Core protocol. Extensions are 
intended to contain multiple requests. 


Major opcodes 128 through 255 are reserved for extensions. 


Every protocol request on a given connection is implicitly assigned a sequence number 
starting with 1 used in replies, errors, and events. 


Using the X Protocol Reply Format 
Every protocol reply contains a 32-bit length field expressed in units of 4 bytes. A protocol 
reply consists of 32 bytes, followed by zero or additional bytes of data, as specified in the 
length field. Unused bytes within a protocol reply are not guaranteed to be the value of 0.A 
protocol reply contains the least significant 16 bits of the sequence number of the 
corresponding protocol request. 


Using the X Protocol Error Format 
Protocol error reports are 32 bytes long. A protocol error includes an 8-bit error code. Every 
error includes the major and minor opcodes of the failed request and the least significant 16 
bits of the sequence number of the request. Unused bytes within an error are not 
guaranteed to be zero. Error codes 128 through 255 are reserved for extensions. 


The failing resource ID is returned for the following errors: 


Colormap Cursor 
Drawable Font 
GContext IDChoice 
Pixmap Window 


The atom that failed is returned for Atom errors. 
The value that failed is returned for Value errors. 


Other Core errors return no additional data. 
Using the X Protocol Event Format 


Protocol events are 32 bytes long. Protocol events contain an 8-bit type code. The most 
significant bit in this code is set if the event is generated by a SendEvent request. Unused 
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bytes within a protocol event are not guaranteed to be the value of 0. Event codes 64 
through 127 are reserved for extensions, although the Core protocol does not define a 
mechanism for selecting interest in such events. Every Core event, with the exception of 
KeymapNotify, contains the least significant 16 bits of the sequence number of the last 
protocol request issued by the client that was, or is currently being, processed by the server. 


Using the X Protocol Syntax 


The following conventions are used to help you identify certain components. 
Component Syntax 
set of alternatives Appear in boldface within braces ({...}). 
set of structure components Appear within brackets ([...]). 
types Appear in UPPERCASE. 
alternative values Appear in Initial Caps. 
requests Appear in this format: 
RequestName 


arg1: type? 


rgN: typeN 
=> 


result1: type 


resultM: typeM 
Errors: kinda, ..., kindK 
Description. 


The return symbol (“=>”) in the request code definition 
indicates the request has one or more replies. If no symbol 
is present, then the request has no reply and is 
asynchronous. Errors can still be reported. 


events Appear in this format: 
EventName 


value1: type1 


valueN: typeN 
Description 


Using Enhanced X-Windows Common Protocol Types 
INT16 and CARD16 are defined in the Xmd.h file of machine-dependent declarations. 
Type Description 


ARC [x, y. INT16 
width, height. CARD16 
angle1, angle2: INT16] 
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ATOM 
BITGRAVITY 


BITMASK 


BOOL 
BUTMASK 
BUTTON 
BYTE 
CHAR2B 
CARD8 
CARD16 
CARD32 
COLORMAP 
CURSOR 


32-bit value (top 3 bits guaranteed to be 0) 


{Forget, Static, 

NorthWest, North, NorthEast, 
West, Center, East, 
SouthWest, South, SouthEast} 


Various requests contain arguments of the following form: 


value-mask. BITMASK 


These values allow the client to specify a subset of a heterogeneous 
collection of optional arguments. The va/ue-mask specifies which arguments 
are to be provided; each such value is assigned a unique bit position. The 
representation of the BITMASK typically contains more bits than there are 
defined values; unused bits in the va/ue-mask must be the value of 0. 
Otherwise, the server generates a Value error. 


{True, False} 

{Button1, Button2, Button3, Button4, Button5} 
CARD8 

8-bit value 

[byte1, byte2: CARD8] 

8-bit unsigned integer 

16-bit unsigned integer 

32-bit unsigned integer 

32-bit value (top 3 bits guaranteed to be 0) 

32-bit value (top 3 bits guaranteed to be 0) 


DEVICEEVENT {KeyPress, KeyRelease, ButtonPress, ButtonRelease, PointerMotion, 


DRAWABLE 
EVENT 


FONT 
FONTABLE 
GCONTEXT 
HOST: 


INT8 


Button1 Motion, Button2Motion, Button3Motion, Button4Motion, 
Button5Motion, ButtonMotion} 


WINDOW or PIXMAP 


{KeyPress, KeyRelease, OwnerGrabButton, ButtonPress, 
ButtonRelease, EnterWindow, LeaveWindow, PointerMotion, 
PointerMotionHint, Button1Motion, Button2Motion, Button3Motion, 
Button4Motion, Button5Motion, ButtonMotion, Exposure, 
VisibilityChange, ResizeRedirect, StructureNotify, SubstructureNotify, 
SubstructureRedirect, FocusChange, PropertyChange, 
ColormapChange, KeymapState} 


32-bit value (top 3 bits guaranteed to be 0) 
FONT or GCONTEXT 
32-bit value (top 3 bits guaranteed to be 0) 


[family. {Internet} 
address: LISTofBYTE] 


The length, format, and interpretation of a HOST address are specific to the 
family 


8-bit signed integer 
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INT16 
INT32 
KEYCODE 


16-bit signed integer 
32-bit signed integer 
CARD8 


KEYBUTMASK KEYMASK or BUTMASK 


KEYMASK 
KEYSYM 
LISTofFOO 


LISTof VALUE 


OR 


PIXMAP 
POINT 


{Shift, Lock, Control, Mod1, Mod2, Mod3, Mod4, Mod5} 
32-bit value (top 3 bits guaranteed to be 0) 


A type name in the form of LISTofFOO means a counted list of elements of 
type FOO. The size of the length field may vary and is not necessarily the 
same size as a FOO. In some cases, the size may be implicit and not fully 
specified in this document. Except where explicitly noted, 0 length lists are 
legal. 


Various requests contain arguments of the following form: 
value-list. LISTofVALUE 


These arguments allow the client to specify a subset of a heterogeneous 
collection of optional arguments. The value-list contains one value for each 
bit set to 1 in the associated BITMASK, from the least to the most significant 
bit in the mask. Each value is represented with 4 bytes, but the actual value 
occupies only the least significant bytes as required. The values of the 
unused bytes do not matter. 


A type of the form T1 or ... or Tn means the union of the indicated types; a 
single-element type is given as the element without enclosing braces. 


32-bit value (top 3 bits guaranteed to be 0) 
[x, y: INT16] 


POINTEREVENT 


RECTANGLE 


STRING8 
STRING16 


TIMESTAMP 
VISUALID 


{ButtonPress, ButtonRelease, EnterWindow, LeaveWindow, 
PointerMotion, PointerMotionHint, Button1 Motion, Button2Motion, 
Button3Motion, Button4Motion, Button5Motion, ButtonMotion 
KeymapState} 


Lx, y. INT16 
width, height. CARD 16] 


The [x, y] coordinates of a RECTANGLE specify the upper-left corner. 
LISTofCARD8 
LISTofCHAR2B 


The primary interpretation of large characters in a STRING16 is that these 
characters are composed of two bytes used to index a 2-D matrix; hence 
the use of CHAR2B rather than CARD16. This corresponds to the JIS/ISO 
method of indexing 2-byte characters. It is expected that most large fonts 
will be defined with 2-byte matrix indexing. For large fonts constructed with 
linear indexing, a CHAR2B can be interpreted as a 16-bit number by 
treating byte? as the most significant byte. This means clients should 
always transmit such 16-bit character values most significant byte first, as 
the sever will never byte swap CHAR2B quantities. 


CARD32 
32-bit value (top 3 bits guaranteed to be 0) 
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VALUE 
WINDOW 


32-bit quantity (used only in LISTof VALUE) 
32-bit value (top 3 bits guaranteed to be 0) 


WINGRAVITY {Unmap, Static, NorthWest, North, NorthEast, West, Center, East, 


SouthWest, South, SouthEast} 


Using the X Protocol Error Codes 
Usually, when a request terminates in an error, the request has no side effects (that is, there 
is no partial execution). The only requests for which this is not true are the 
ChangeWindowéAittributes, the ChangeGC, the PolyText8, the PolyText16, the 
FreeColors, the StoreColors, and the ChangeKeyboardControl protocol requests. 


These error codes can be returned by the protocol requests. An error code can be returned 
for more than one reason. 


Error Code 


Access 


Alloc 


ATOM 


Colormap 


Cursor 


Drawable 


Font 


Cause 


A client attempted to grab a key or button combination already grabbed by 
another client. 


A client attempted to free a colormap entry that it did not already allocate. 


A client attempted to store into a read-only or an unallocated colormap 
entry. 


A client attempted to modify the access control list from a host other than 
the local (or otherwise authorized client). 


A client attempted to select an event type that another client has already 
selected and only one client can select at a time. 


The server failed to allocate the requested resource or server memory. 


Note: This only covers allocation errors at a very course level and is not 
intended to cover all cases of a server running out of allocation space in the 
middle of service. The semantics when a server runs out of allocation space 
are left unspecified, but the server may generate an Alloc error on any 
request for this reason and that client should be prepared to receive such 
events and discard them. 


A value for an ATOM argument does not name a defined ATOM. 
A value for a Colormap argument does not name a defined Colormap. 


The variable type is extended by union with a set of fixed alternatives, for 
example, <WINDOW or PointerRoot or None>. 


A value for a Cursor argument does not name a defined Cursor. 


The variable type is extended by union with a set of fixed alternatives, for 
example, <WINDOW or PointerRoot or None>. 


A value for a Drawable argument does not name a defined window or 
Pixmap. 


The variable type is extended by union with a set of fixed alternatives, for 
example, <WINDOW or PointerRoot or None>. 


A value for a Font arguemnt does not name a defined Font. 


A value for a Fontable argument does not name a defined font or a defined 
GContext. 
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GContext 


IDChoice 


The variable type is extended by union with a set of fixed alternatives, for 
example, <WINDOW or PointerRoot or None>. 


A value for a GContext argument does not name a defined GContext. 


The variable type is extended by union with a set of fixed alternatives, for 
example, <WINDOW or PointerRoot or None>. 


The value chosen for a resource identifier is either not included in the range 
assigned to the client or is already in use. 


implementation 


Length 


Match 


Name 


Pixmap 


Request 


Value 


Window 


The server does not implement some aspect of the request. A server that 
generates this error for a core request is deficient. As such, this error is not 
listed for any of the requests, but clients should be prepared to receive such 
errors and handle or discard them. 


The length of a request is shorter or longer than that minimally required to 
contain the variables. 


The length of a request exceeds the maximum length required accepted by 
the server. 


In a graphics request, the root and depth of the GContext argument does 
not match that of the destination. 


An InputOnly window is used as a Drawable argument. 


Some argument or pair of arguments has the correct type and range but 
fails to match in some other way required by the request. 


A font or color of the specified name does not exist. 
A value for a Pixmap argument does not name a defined Pixmap. 


The variable type is extended by union with a set of fixed alternatives, for 
example, <WINDOW or PointerRoot or None>. 


The major or minor opcode does not specify a valid request. 


Some numeric value falls outside the range of values accepted by the 
request. Unless a specific range is specified for an argument, the full range 
defined by the arguemnts type is accepted. Any argument defined as a set 
of alternatives can generate this error due to the encoding. 


A value for a Window argument does not name a defined Window. 


The variable type is extended by union with a set of fixed alternatives, for 
example, <WINDOW or PointerRoot or None>. 


Using Enhanced X-Windows with Predefined Atoms 
Predefined atoms are not necessary and may not be useful in all environments, but 
eliminate many InternAtom requests in most applications. Note that predefined is used for 
numeric values, not for required semantics. The Core protocol imposes no semantics on 
these names, except as they are used in the FONTPROP structures. 


The following names have predefined atom values. (These atom names should be all 


uppercase.) 


ARC 

ATOM 
BITMAP 
CAP_HEIGHT 


ITALIC_ANGLE STRING 
MAX_SPACE SUBSCRIPT_X 
MIN_SPACE SUBSCRIPT_Y 
NORM_SPACE SUPERSCRIPT_X 


Chapter 5. Enhanced X-Windows 5-253 


CARDINAL 
COLORMAP 
COPYRIGHT 
CURSOR 
CUT_BUFFERO 
CUT_BUFFER1 
CUT_BUFFER2 
CUT_BUFFER3 
CUT_BUFFER4 
CUT_BUFFERS 
CUT_BUFFER6 
CUT_BUFFER7 
DRAWABLE 
END_SPACE 
FAMILY_NAME 
FONT 
FONT_NAME 
FULL_NAME 
INTEGER 


NOTICE 

PIXMAP 

POINT 

POINT_SIZE 

PRIMARY 
QUAD_WIDTH 
RECTANGLE 
RESOLUTION 
RESOURCE_MANAGER 
RGB_BEST_MAP 
RGB_BLUE-MAP 
RGB_COLOR_MAP 
RGB_DEFAULT_MAP 
RGB_GRAY_MAP 
RGB_GREEN_MAP 
RGB_RED_MAP 
SECONDARY 
STRIKEOUT_ASCENT 
STRIKEOUT_DESCENT 


SUPERSCRIPT_Y 
UNDERLINE_POSITION 
UNDERLINE_ THICKNESS 
VISUALID 

WEIGHT 

WINDOW 

WM_CLASS 
WM_CLIENT_MACHINE 
WM_COMMAND 
WM_HINTS 
WM_ICON_NAME 
WM_ICON_SIZE 
WM_NAME 
WM_NORMAL_HINTS 
WM_SIZE_HINTS 
WM_TRANSIENT_FOR 
WM_ZOOM_HINTS 
X_HEIGHT 


Names private to a particular application or end user, but stored in globally accessible 
locations, should begin with two leading underscores. To avoid conflicts with other names, 
for which semantics might be imposed (either at the protocol level or in terms of higher level 
user interface models), names beginning with an underscore should be used for atoms that 
are private to a particular vendor or organization. To guarantee that conflicts between 
vendors and organizations are avoided, additional prefixes should be used, but the 


mechanism for choosing such prefixes is not defined here. 


Using Enhanced X-Windows to Set Up a Remote Connection 
For remote clients, the X protocol can be built on top of any reliable byte stream. Use the 
following steps to set up a connection. 


The client must send an initial byte of data to identify the byte order to be used. The value of 
the byte must be octal 102 or 154. 


The octal 102 (ASCII uppercase B) means values are transmitted with the most-significant 
byte first. Octal 154 (ASCII lowercase I!) means values are transmitted with the 
least-significant byte first. Except where explicitly noted in the protocol, all 16-bit and 32-bit 
quantities sent by the client must be transmitted with this byte order, and all 16-bit and 32-bit 
quantities returned by the server will be transmitted with this byte order. 


After the byte-order byte, the following information is transmitted by the client at connection 


setup time: 
e protocol-major-version: 


e protocol-minor-version: 


e authorization-protocol-name: 


e authorization-protocol-data: 


CARD16 
CARD16 
STRINGS 
STRINGS 


The version numbers indicate the version of the protocol the client expects the server to 


implement. 


The authorization name indicates the authorization protocol the client expects the server to 
use and the data specific to that protocol. 


Specifying valid authorization mechanisms is not part of the Core protocol. IH’s hoped 
eventually, one authorization protocol will be agreed upon. In the meantime, a server that 
implements a protocol other than the protocol the client expects or a server that implements 
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only the host-based mechanism can simply ignore this information. If both name and data 
strings are empty, this occurrence is to be interpreted as no explicit authorization. 


The client receives the information in the following order. 


e success: BOOL 

e protocol-major-version: CARD16 
e protocol-minor-version: CARD16 
e length: CARD16 


The /ength is the amount (in units of 4-bytes) of additional data to follow. 


The version numbers are for future protocol revisions. Generally, the major version would 
increment for incompatible changes and the minor version would increment for small upward 
compatible changes. If there are no other protocol revisions, the major version is 11, and the 
minor version is zero. 


The protocol version numbers indicate the protocol version supported by the server. The 
protocol version supported by the server may not equal the version sent by the client. The 
server can, but does not have to, refuse connections from clients with a version different 
from the version supported by the server. A server can, but does not have to, support more 
than one version simultaneously. 


The client receives the following additional data if authorization fails: 


e reason: STRINGS 
The client receives the following additional data if authorization is accepted: 
e vendor: — STRINGS 
e release-number: CARD32 


e resource-id-base,resource-id-mask: CARD32 


e image-byte-order: {LSBFirst, MSBFirst} 
e bitmap-scanline-unit: {8, 16, 32} 

e bitmap-scanline-pad: {8, 16, 32} 

e bitmap-bit-order: {LeastSignificant, MostSignificant} 
e pixmap-formats: LISTofFORMAT 

° roots: LISTofSCREEN 

e motion-buffer-size: CARD32 

e maximum-request-length: CARD16 

e min-keycode.max-keycode: KEYCODE 

where: 

FORMAT: [depth: CARD8, 


bits-per-pixel: {1, 4, 8, 16, 24, 32} 
scanline-pad: {8, 16, 32}] 
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SCREEN: [root: WINDOW 
width-in-pixels, height-in-pixels: CARD16 
width-in-millimeters, height-in-millimeters: CARD16 
allowed-depths: LISTofDEPTH 
root-depth: CARD8 
root-visual: VISUALID 
default-colormap: COLORMAP 
white-pixel, black-pixel: CARD32 
min-installed-maps, max-installed-maps: CARD16 
backing-stores: {Never, WhenMapped, Always} 
save-unders: BOOL 
current-input-masks: SETofEVENT} 


DEPTH: [depth: CARD8 
visuals: LISTofVISUALTYPE] 
VISUALTYPE: [visual-id: VISUALID 


class: {StaticGray, StaticColor, TrueColor, GrayScale, 
PseudoColor, DirectColor} 

red-mask: CARD32 

green-mask: CARD32 

blue-mask: CARD32 

bits-per-rgb-value: CARD8 

colormap-entries: CARD16] 


The following information is global to the server: 
e The vendor string gives some identification to the owner of the server implementation. 
e The vendor controls the semantics of the release number. 


e The resource-id-mask contains a single contiguous set of bits (at least 18). The client 
allocates resource IDs by choosing a value with only a subset of these bits set and ORing 
it with resource-id-base for the following types: WINDOW, PIXMAP, CURSOR, FONT, 
GCONTEXT, and COLORMAP. Only values constructed in this way can be used to name 
newly created resources over this connection. Resource |Ds never have the top three bits 
set. The client is not restricted to linear or contiguous allocation of resource IDs. An ID, 
once freed, can be reused. 


An 1D must be unique with respect to the IDs of all other resources, not just other 
resources of the same type. Note, however, that the value spaces of resource identifiers, 
atoms, visualids, and keysyms are distinguished by context. As such, they are not 
required to be disjointed. For example, a given numeric value might be both a valid 
window ID and a valid atom as well as a valid keysym. 


e Although the server is, in general, responsible for byte-swapping data to match the client, 
images are always transmitted and received in formats (including byte order) specified by 
the server. The byte order for images is given by image-byte-order, and applies to each 
scanline unit in XYFormat (bitmap) format and to each pixel value in ZFormat. 


e A bitmap is represented in scanline order. Each scanline is padded to a multiple of bits as 
given by bitmap-scanline-pad. The pad bits are of arbitrary value. 


The scanline is quantified in multiples of bits as given by bitmap-scanline-unit. The 
bitmap-scanline-unit is always less than or equal to the bitmap-scanline-pad. 


Within each unit, the leftmost bit in the bitmap is either the least-significant bit or the 
most-significant bit in the unit, as given by bitmap-bit-order. |\f a pixmap is represented in 


{ 
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XYFormat, each plane is represented as a bitmap, and the planes appear from the 
most-significant to the least-significant in bit order, with no padding between planes. 


The pixmap-formats contains one entry for each depth value. The entry describes the 
ZFormat used to represent images of that depth. An entry for a depth is included if any 
screen supports that depth, and all screens supporting that depth must support only that 
ZFormat for that depth. In ZFormat, the pixels are in scanline order, left to right, within a 
scaniine. 


The number of bits used to hold each pixel is given by bits-per-pixel. These may be larger 
than strictly required by the depth, in which case the least-significant bits hold the pixmap 
data and the values of the unused high-order bits are undefined. When the bits-per-pixel 
is four, the order of nibbles in the byte is the same as the image-byte-order. When the 
bits-per-pixel is one; the format is identical for bitmap format. Each scanline is padded to 
a multiple of bits as given by scanline-pad; when bits-per-pixel is one, this will be identical 
to bitmap-scanline-pad. 


The server implementation, which is transparent to the protocol, determines how a 
pointing device moves on the screen. No geometry among screens is defined. 


The server can retain the recent history of pointer motion with a finer granularity than is 
reported by MotionNotify events. Such history is available by using the 
GetMotionEvents request. The approximate size of the history buffer is given by 
motion-buffer-size. 


The maximum-request-length specifies in 4-byte units the maximum length of a request 
that can be accepted by the server. Requests larger than this value generate a Length 
error. lf an error is generated, server reads and discards the entire request; the 
maximum-request-length is always at least 4096. Requests, up to and including 16384 
bytes in length, are accepted by all servers. 


The min-keycode specifies the smallest keycode values transmitted by the server. The 
min-keycode is never less than 8. 


The max-keycode specifies the largest keycode values transmitted by the server. The 
max-keycode is never greater than 255. Not all keycodes in this range are required to 
have corresponding keys. 


The following information is provided about each screen: 


The allowed-depths specifies which pixmap and window depths are supported. Pixmaps 
are supported for each depth listed. Windows of that depth are supported if at least one 
visual type is listed for the depth. A pixmap depth of one is always supported and listed, 
but windows of depth one might not be supported. A depth of zero is never listed, but 
zero-depth InputOnly windows are always supported. 


The root-depth specifies the depth of the root window. 
The root-visual specifies the visual type of the root window. 


The width-in-pixels and height-in-pixels specify the size of the root window. The 
width-in-pixels and height-in-pixels cannot be changed. 


The class of the root window is always InputOutput. 


The width-in-millimeters and height-in-millimeters can be used to determine the physical 
size and the aspect ratio. 


The default-colormap is the colormap initially associated with the root window. Clients 
with minimal color requirements, that are creating windows of the same depth as the root 
window, may want to allocate from this colormap by default. 
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The black-pixel and white-pixel can be used in implementing a monochrome application. 
These pixel values are for permanently allocated entries in the default-colormap. The 
actual RGB values can be set on some screens and may not actually be black and white. 
The names black and white are intended to convey the expected relative intensity of the 
colors. 


The border of the root window is initially a pixmap filled with the black-pixel. The initial 
background of the root window is a pixmap filled with some unspecified two-color pattern 
using black-pixel and white-pixel. 


The min-installed-maps specifies the number of colormaps that can be guaranteed to be 
installed simultaneously with InstallColormap, regardless of the number of entries 
allocated in each colormap. 


The max-installed-maps field specifies the maximum number of colormaps that can be 
installed simultaneously, depending on their allocations. Multiple static-visual colormaps 
with identical contents but different resource IDs should be considered as a single 
colormap for the purposes of this number. The values for a single hardware colormap is a 
one. 


The backing-stores indicates when the server supports backing stores for this screen. 
However, the backing store might have limited storage for the number of windows it can 
support simultaneously. 


If save-unders field is the value of True, then the server can support the save-under mode 
in CreateWindow and ChangeWindowaAttributes, although again it may be limited 
storage. 


The current-input-events field is the value returned by GetWindowaAttributes for the 
all-event-masks field for the root window. 


The following information is provided about each visual type: 


A visual type can be listed for more than one depth or for more than one screen. 


For PseudoColor, a pixel value indexes a colormap that produces independent RGB 
values. The RGB values can be changed dynamically. 


For GrayScale, a pixel value indexes a colormap that produces independent RGB values, 
except that the primary that drives the screen is undefined. Consequently, the client 
should always store the same value for red, green, and blue in colormaps. 


For DirectColor, a pixel value is decomposed into separate RGB subfields, and each 
subfield separately indexes the colormap indexes for the corresponding value. The RGB 
values can be changed dynamically. 


The red-mask, green-mask, and blue-mask are defined for DirectColor. Each mask has 
one contiguous set of bits set to 1 with no intersections. Each mask usually has the same 
number of one bits. 


For TrueColor, a pixel value is decomposed into separate RGB subfields, and each 
subfield separately indexes the colormap indexes for the corresponding value. This 
colormap has predefined read-only RGB values which are server-dependent, but provide 
near-linear or linear increasing ramps in each primary. 


The red-mask, green-mask, and blue-mask fields are defined for TrueColor. Each mask 
has one contiguous set of bits set to 1 with no intersections. Each mask usually has the 
same number of one bits. 
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e For StaticColor, a pixel! value indexes a colormap that produces independent RGB 
values. This colormap has predefined read-only RGB values, which are 
server-dependent. 


e For StaticGray, a pixel value indexes a colormap that produces independent RGB 
values. The red, green, and blue values in this colormap are equal for any single pixel 
value, resulting in shades of gray. StaticGray with a 2-entry colormap can be thought of 
as monochrome. 


e The bits-per-rgb-value field specifies the log base 2, the number of distinct color intensity 
values (individually) of red, green, and blue. This number is not necessarily related to the 
number of colormap entries. Actual RGB values are always passed in the protocol within 
a 16-bit spectrum, with zero being minimum intensity and 65535 being the maximum 
intensity. On hardware that provides a linear zero-based intensity ramp, the following 
relationship exists: 


hw-intensity = protocol-intensity / (65536 / 
total-hw-intensities ) 


e Colormap entries are indexed from 0. The colormap-entries defines the number of 
colormap entries available in a newly created colormap. For DirectColor and TrueColor, 
this is usually two to the power of the maximum number of one bits in red-mask, 
green-mask, and blue-mask. 


Using Enhanced X-Windows to Close Connections to the Server 
At the time of connection close, all event selections made by the client are discarded in the 
following ways: 


e Ifthe client has the pointer actively grabbed, an UngrabPointer is performed, . 


e Ifthe client has the keyboard actively grabbed, an UngrabKeyboard is performed. All 
passive grabs by the client are released. 


If the client has the server grabbed, an UngrabServer is performed, disowning all 
selections owned by the client. 


All selections owned by the client are disowned. 


lf close-down mode is RetainPermanent or RetainTemporary, then all resources, 
including colormap entries, allocated by the client are marked as permanent or temporary. 
This marking does not prevent other clients from destroying these resources explicitly. 


If the mode is Destroy, all client resources are destroyed. 


When the resources of a client and the members in the client save-set, that is an inferior 
of a window created by the client, are destroyed, the save-set window is reparented to the 
closest ancestor so that the save-set window is not an inferior of a window created by the 
client. If the save-set window is unmapped, a MapWindow request is performed on it, 
even if it is not an inferior of a window created by the client. The reparenting leaves 
unchanges the absolute coordinates (with respect to the root window) of the upper-left 
outer corner of the same set window. After save-set processing, all windows created by 
the client are destroyed. For each non-window resource created by the client, the 
appropriate Free request is performed. All colors and colormap entries allocated by the 
client are freed. 


When the last connection to a server closes, a server goes through a cycle of having no 
connections and having some connections. The server resets its state to its initial state as 
if it had just been started, with each transition of the state having no connections (that is, 
the Destroy close-down mode forced a connection closing). The server starts the cycle 
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by destroying all lingering resources of clients that were terminated in RetainPermanent 
or RetainTemporary mode. The X Server does the following: 


e Deletes everything except the predefined atom identifiers 

e Deletes all the properties on all root windows 

e Resets all device maps and attributes (key click, bell volume, acceleration) to initial value 
e Resets the access control list to initial value 

e Restores the standard root tiles and cursors to initial value 

e Restores the default font path to initial value 

e Restores the input focus to state PointerRoot. 


Closing a connection with a close-down mode of RetainPermanent or RetainTemporary 
does not reset the server. 


Using Enhanced X-Windows to Generate an Event 
When a button is pressed with the pointer in window W and no active pointer grab is in 
progress, then the ancestors of W are searched from the root down for a passive grab to 
activate. If a matching passive grab on the button does not exist, then an active grab is 
started automatically for the client receiving the event, and the /ast-pointer-grab time is set to 
the current server time. The effect is equivalent to a GrabButton protocol request with the 
following arguments: 


Argument Value 

event-window The event window. 

event-mask Selected pointer events of the client on the event window. 

pointer-mode Asynchronous. 

keyboard-mode Asynchronous. 

owner-events True if the client has OwnerGrabButton selected on the event window. 
Otherwise, it is set to the value of False. 

confine-to None. 

cursor None. 


The grab is terminated automatically when all the buttons are released. UngrabPointer and 
ChangeActiveGrab can both be used to modify the active grab. 


Using Enhanced X-Windows to Control Flow and Concurrency 
When the server is writing to a specific connection, it can stop reading from that connection. 
However, if the writing blocks, the server must continue to service other connections. The 
server is not required to buffer more than a single request per connection at one time. For a 
given connection to the server, a client can block while reading from the connection, but 
should undertake to read (events and errors) when writing would block. Failure on the part of 
a client to do this could result in a deadlocked connection, although deadiock is unlikely 
unless the transport layer has very little buffering, or the client attempts to send large 
numbers of requests without reading replies or checking for errors and events. 


If a server is implemented with internal concurrency, the overall effect must be that individual 
requests are executed to completion in a serial order, and that requests from a given 
connection are executed in delivery order. In other words, the total execution order is a 
shuffle of the individual streams. The execution of a request includes validating all 
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arguments, collecting all data for any reply, and generating (and queueing) all required 
events, but does not include the actual transmission of the reply and the events. In addition, 
the effect of any other cause, such as the activation of a pointer motion that can generate 
multiple events, must effectively generate (and queue) all required events indivisibly with 
respect to all other causes and requests. For a request from a given client, any events 
destined for that client which are caused by executing the request must be sent to the client 
before any error or reply is sent. 


Related Information 
The QueryFont protocol request, SetCloseDownMode protocol request, 
SetSelectionOwner protocol request. 


The aixterm Command HFT Display Characteristics Overview 
VTLs are supported with the following characteristics: 


e Locator reports are given for the following mouse events: 


ButtonPress 

— ButtonRelease 

— MotionNotify (with any button down) 
—- LeftDownMotion 

— MiddleDownMotion 


e Locator reports are given in absolute coordinates. 
e Locator motion is processed in compressed mode. 


e Applications need not display a locator cursor. 














HFT 


Faneion————SS*dzT [ator 
PTERMINALCONTROL || 
[Set Echo and Break Wap [ioc _|no suppor 
[SetKeyboardMap ioctl ‘Rt 
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impor SCC 
mouse «VTL support 
ais ~«i_ ro support 
[Sound Complete __—_—_——~(stgnal__[no-support 
our 








Cancel Sound 
Change Physical Display 


Related Information 
The aixterm command 





Using the aixterm Command Datastream Support 
The following is a list of the escape sequences supported by the aixterm command. 


Some escape sequences activate and deactivate an alternate screen buffer that is the same 
size as the display area of the window. This capability allows the contents of the screen to 
be saved and restored. When the alternate screen is activated, the current screen is saved 
and replaced with the alternate screen. The saving of lines scrolled off of the window is 
disabled until the original screen is restored. 


This table uses these abbreviations in the righthand column: 


Xv Supported by the aixterm command running in vt100 mode. 
Xh Supported by the aixterm command running in hft mode. 

H Found in the hft datastream. 

V Found in the vt100 datastream. 
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[Name [Function ______—‘[Oatastream ——~(Support__ 
[__|SINGLE-BYTEGONTROIS «| SSC~dSC“‘~S™! 
Eo (ne 
xv, xh, HV 
Shift in }OxOF =X, Xh,, H, V 
. 

, 


Substitute (also cancels) H,V 

S54 [Single SHAY 
S53 [Sng tar 
S51 | Sgt rt} Joe fr 
eh |srsertorzniaab ES Pn —[F 


cursor vertical tab ESC[PnY 
dat 


DEVICE ATTRIBUTES 
request (host to vt100) 
request (host to vt100) ESC [Oc Xv, Xh, V 
response (vt100 to host) ESC[?1;2c Xv, Xh, V 


ESCIPnP Xv, XR H 
screen alignment display ESC #8 Xv, Xh, V 





Lc} rc} zr 
<|<|< 


HT 
LF 
VT 
FF 
CR 
SO 
SI 
DC1 
DC3 
CAN 
SUB 






i?) 


i?) 





















ESC[c Xv, Xh, V 
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deck- 


keypad application mode ESC = 
pam 
deckpn | keypad numeric mode 
m 


restore cursor & attributes ESC 8 
decsc save cursor & attributes ESC 7 : 
decstbm | set top & bottom margins ESC [ Pt; Por 


device status report ESC [Psn 
0 response from vt100: ready 

5 command from host: please 

report status 

6 command from host: report 

active position 

13 error report sent from 

virtual terminal to host 


disable manual input ~ | ESC ‘ (back quote) 








Q. 
” 
=< 











Xv, Xh, V 
Xv, Xh, V 


Xv, Xh, H, V 



















Xv, Xh, H 
Xv, Xh, H 
Xv, Xh, H 








Xv, Xh, H, V 
Xv, Xh, H, V 
Xv, Xh, H, V 


emi enable manual input ESC b H 

2 erase ail of area 

erase display 
0 erase to end of display 

erase line ESC[PsK 
0 erase to end of line Xv, Xh, H, V 
1 erase from start of line 
2 erase all of line Xv, Xh, H, V 

ferase charactor ———SSSSS=«L ESOL PX Xi, Xi H 

horizontal tab stop ESCH Xv, Xh, H, V 


erase area ESC[PsO 
1 erase from display star 
horizontal and vertical position ESC [ PI; Pef Xv, Xh, H, V 


0 erase to end of area 
ESC[PsJ 
2 erase all of display 
ESO[Pn@ Xv, XhH 


1 erase from area start 
erase field—e,s,all 
0 erase to end of field 
1 erase from field start 
2 erase all of field 
Xv, Xh, H, V 
ech 
hts 
hvp 
ich 
fd [index SC*dESC «XR 
xv 
[so [leckswn@sSC=*dESGCid 


retreive esc SEEN 
keyboard status information ESC[Psp 
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fis__[resettoiniialstate «ESC 
See "set mode” below in this column. 


reset mode, other private modes and 
XTERM private modes: See "set 
mode” below in this column. 
restore mode, other private modes 
and XTERM private modes: See "set 
mode” below in this column. 






















save mode, other private modes and 
XTERM private modes: See "set 
mode”. below in this column. 


United Kingdom Set 


ASCII Set (USASCII) 








special graphics ESC (0 
ESC)O (G1) 
ESC *0O (G2) 


ESC +0 (G3) 


$s3 single shift G3 ESCO X 


jsu__|serotup__———SC«wESS TPS x 








Vv 
v, Xh, H 
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set graphic rendition 
0 normal 
1 bold 
4 underscore 
5 blink (appears as bold) 
7 reverse 
8 invisible | 
10..17 fonts 
30..37 foreground colors 
40..47 background colors 
90..97 foreground colors 
100..107 background colors 
soda 
sata | 
sm 


ANSI specified modes 
4 1RM insert mode 
12 SRM send/rec mode 
18 TSM tab stop mode 
20 LNM linefeed/newline 


Other private modes 
1 normal/application cursor 
3 80/132 columns 

4 smooth/jump scroll 

5 reverse/normal video 

6 origin/normal 

7 on/off autowrap 

8 on/off autorept 

21 CNM CR-NL 


XTERM private modes 

40 132/80 column mode 

41 curses(5) fix 

42 hide/show scrollbar 

43 on/off save scroll text 

44 on/off margin bell 

45 on/off reverse wraparound 





48 reverse/normal status line 
49 page/norma! scroll mode 


tabulation clear 
0 clear horizontal tab stop at 
active position 
1 vertical tab at line indicated 
by cursor 
2 horizontal tabs on line 
3 all horizontal tabs 
4 all vertical tabs 
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set GO character set ESC (< 
soi ESO) < 
i 


47 alternate/normal screen buffer 


ESC[Psm 









ESC [Ps;...;Ps h 





ESC [?Ps:...:Psh 






















Xv, V 
Xv, Xh, V 
Xv, Xh, V 
Xv, Xh, V 
Xv, Xh, V 
Xv, Xh, H, V 
Xv, Xh, V 
H 










ESC [Ps g (default Ps =0) 





Xv, Xh, H, V 





H 











H 
Xv, Xh, H, V 
H 









VTD 


[Vio [wtualternnaldata «dS 
sree sep fest 
rt [oss res [7 Tra 
fs reuin om taustne————~S=*dESCL? FX 
fss__[show siausiing————~«*zESOL®S «RH 
pgs_[soiocoumnetsiausine —Jeserrs7 xx 


set text parameters ESC iF Ps ; Pt \007 XV, Xh 
0 change window name and 
title to Pt 

































Related Information 
The aixterm command. 


List of the Xlib Library Cursor Fonts 


The following is a list of cursors and their shapes in fonts that are currently available with 
Enhanced X-Windows. These cursors are defined in the /usr/include/XIl/cursorfont.h 


directory. 

#define XC_num_glyphs 154 
#define XC_X_cursor 0 
#define XC_arrow 2 
#define XC_based_arrow_down 4 
#define XC_based_arrow_up 6 
#define XC_boat 8 
#define XC_bogosity 10 
#define XC_bottom_left_corner 12 


#define XC_bottom_right_corner 14 


#define XC_bottom_side 16 
#define XC_bottom_tee 18 
#define XC_box_sprial 20 
#define XC_center_ptr 22 
#define XC_circle 24 
#define XC_clock 26 
#define XC_coffee_mug 28 
#define XC_cross_ . 30 
#define XC_cross_reverse 32 
#define XC_crosshair 34 
#define XC_diamond_cross 36 
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#define 
#define 
#define 
#define 
#define 
#define 
#define 
#define 
#define 
#define 
#define 
#define 
#define 
#define 
#define 
#define 
#define 
#define 
#define 
#define 
#define 
#define 
#define 
#define 
#define 
#define 
#define 
#define 
#define 
#define 
#define 
#define 
#define 
#define 
#define 
#define 
#define 
#define 


XC_dot 
XC_dotbox 
XC_double_arrow 
XC_draft_large 
XC_draft_small 
XC_draped_box 
XC_exchange 

XC_ fleur 
XC_gobbler 
XC_gumby 
XC_hand1 
XC_hand2 
XC_heart 

XC_icon 
XC_iron_cross 
XC_left_ptr 
XC_left_side 
XC_left_tee 
XC_leftbutton 
XC_Il_angle 
XC_!r_angle 
XC_man 
XC_middlebutton 
XC_mouse 
XC_pencil 
XC_pirate 

XC_plus 
XC_question_arrow 
XC_right_ptr 
XC_right_side 
XC_right_tee 
XC_rightbutton 
XC_rtl_logo 

XC_ sailboat 
XC_sb_down_arrow 
XC_sb_h_double_arrow 
XC_sb_left_arrow 
XC_sb_right_arrow 
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38 
40 
42 
44 
46 
48 
50 
52 
54 
56 
58 
60 
62 
64 
66 
68 
70 
72 
74 
76 
78 
80 


82 


84 
86 
88 
90 
92 
94 
96 
98 
100 
102 
104 
106 
108 
110 
112 


#define 
#define 
#define 
#define 
#define 
#define 
#define 
#define 
#define 
#define 
#define 
#define 
#define 
#define 
#define 
#define 
#define 
#define 
#define 
#define 
#define 


Related Information 


XC_sb_up_ arrow 
XC_sb_v_double_arrow 
XC_shuttle 
XC_sizing 
XC_spider 
XC_spraycan 
XC_star 

XC_target 
XC_tcross 

XC_top _left_arrow 
XC_top_left_corner 
XC_top_right_corner 
XC_top_side 
XC_top tee 
XC_trek 
XC_ul_angle 
XC_umbrella 
XC_ur_angle 
XC_watch 
XC_xterm 
XC_aixwm 


The XCreateFontCursor subroutine. 


114 
116 
118 
120 
122 
124 
126 
128 
130 
132 
134 
136 
138 
140 
142 
144 
146 
148 
150 
152 
154 


Chapter 5. Enhanced X-Windows 5-269 


5—270 AIX User Interface Programming Concepts 


Chapter 6. Curses and Extended Curses 





Curses and Extended Curses Overview 


The IBM AIX Version 3 for RISC System/6000 contains two libraries of routines to support 
input and output to the terminal screen. These libraries are curses and Extended curses. 


curses is a set of screen control routines. This library is included for compatibility with 
existing application programs. 


Minicurses is a subset of curses that does not allow you to manipulate more than one 
window. You invoke this subset by issuing -DMINICURSES as a CC option. This subset is 
smailer and faster than the full curses interface. 


The full curses interface allows you to manipulate data structures. These data structures are 
called WINDOWS, and they can be thought of as two—dimensional arrays of characters 
representing all or part of the screen. A default window called stdscr is supplied, and you 
can create others using the newwin routine. | 


Windows are referred to by variables declared WINDOW *. The type WINDOW is defined in 
curses.h to be aa C structure. You manipulate these data structures with routines provided 
by curses and extended curses. The most basic routines are move and addch. The 
refresh routine makes the screen look like stdscr (standard screen). 


Routine names beginning with W allow you to specify a window. Routine names not 
beginning with a W affect stdscr. : 


This chapter includes information about the following topics: 


Using the Curses Subroutine Library 

Using the Extended Curses Subroutine Library 
How to Write to a Window 

How to Control the Screen 

How to Define Panels and Panes 

How to Create Panels and Panes 

How to Use the Extended Curses Library 

How to Set Up the Extended Curses Environment 
Curses Programming Example 

Screen ATtributes Sample Program 


Using the Curses Subroutine Library 
The curses subroutine package updates the screen with reasonable optimization. You use 
the term.h header file only if you are using the Terminfo Level Subroutines. 


To initialize the routines which are described in the curses library, you must call the initser 
routine before using any other routines which affect windows and screens. The routine 
endwin should be called before exiting. To get character—at—a-time input without echoing, 
call the cbreak and noecho routines. Most interactive screen—oriented programs require the 
character—at—a-—time input without echoing. 


If the environment variable TERMINFO is defined, any program using curses checks for a 
local terminal definition before checking in /usr/lib/terminfo. For example, TERM is set to 
vt100, then normally, the compiled file is found in /usr/lib/terminfo/v/vt100. (The directory 
name v is copied from the first letter of vt100 to avoid creating large directories.) If, for 
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example, TERMINFO is set to /usr/mark/myterms, curses first checks - 
/usr/mark/myterms/v/vt100. If this file does not exist, curses then checks 
/usr/lib/terminfo/v/vt100. This is useful for developing expenmenta definitions or when 
write permission in /usr/lib/terminfo is not available. 


Note: The plotting library (plot), and the curses library (curses), both use the names erase 
and move. The curses versions are macros. If you need both libraries, put the plot 
code in a different source file than the curses code, or include the following 
statements in the plot code: 


#undef move( ) 
#undef erase( ) 


Using Terminfo Level Subroutines 


To use the terminfo level subroutines of curses, include the curses.h and term.h files, in 
that order, to get the definitions for these strings, numbers, and flags. Programs should call 
the setupterm subroutine before using any of the other terminfo subroutines. The 
setupterm subroutine defines the set of terminal-dependent variables defined in the 
terminfo file. 


If your program needs only one terminal, you can specify the -DSINGLE flag to the C 
compiler. This results in static references instead of dynamic references to capabilities. The 
result is more concise code, but only one terminal can be used at a time for the program. 


Capabilities with a Boolean value have the value 1 if the capability is present and 0 if it is 
not. Numeric capabilities have a value of —1 if the capability is missing and a value of 0 or 
greater if it is present. String capabilities have a NULL value if the capability is missing and 
otherwise have type char * and point to a character string that contains the capability. 
Special character codes that use the \ (backslash) and “ (circumflex) characters are 
transformed into the appropriate ASCII characters. Padding information of the form 

$ <time>, and parameter information befinning with % (percent) are left uninterpreted. The 
tputs routine interprets padding information. The tparm routine interprets parameter 
information. 


All terminfo strings (including the output of tparm) should be printed using tputs or putp. 
Before exiting, your program should call reset_shell_mode to restore the tty modes. 
Programs desiring shell escapes can call reset_shell_mode before the shell is called, and 
reset_prog_mode after returning from the shell. 


Using the Extended Curses Subroutine Library 
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Extended Curses is an enhancement to the curses set of routines that provides extended 
funtion for: 


e Expanded character set 


e Color 


_e Multiple character attributes 


e Error detection and handling 
e Efficient handling of a window—oriented screen presentation, including: - 
— Window stacking and layers . 
~ Linked scrolling of windows . 
- Scrolling data in windows that are partially covered 
- Automatic tracking of active panes 
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e 2-byte characters for international character support 
e locator input support 


Use the preceding routines for new program development or to increase the function of 
existing programs. 


The extended curses library contains a set of C language routines that provide the 
following enhancements: 


e Updates a screen. 

e Gets input from the terminal in a screen—oriented fashion. 

e Moves the cursor from one point to another independent of other screen activities. 
e Creates and manages a screen containing windows, panels and panes. 
e A wider range of display attributes 

e Generalized drawing of boxes 

e Terminal—independent input data processing 

e Extended window control 

e Pane, panel, and field concepts 

e Support for extended characters 

e Handling of locator input. 


The routines do the most common type of terminalI—dependent funtions. The routines use 
the file /usr/lib/terminfo to describe what the terminal can do. 


You can use motion optimization by itself. You can use screen updating and input without 
knowing about either motion optimization or the data. 


The following information is provided to assist you in using the Extended curses Subroutine 
Library: 


Extended curses Subroutine Library terminology 
Using Terminfo Level Subroutines 
Using Screen Update Routines 
Changing Display Attributes 
‘ Controlling Input with the keypad, extended, and trackloc Routines 
Scrolling Windows 
Improving Performance 


Extended curses Subroutine Library Terminology 
The following terms are used in the Extended curses routines: 


window The internal representation of what a portion of the display may look like at 
some point in time. Windows can be any size from the entire display screen 
to a single character. 


screen A window that is large as the display screen. A screen named stdscr is 
automatically provided. 


terminal Sometimes called a terminal screen. A special screen that is the Extended 
Curses package’s understanding of what the work station’s display screen 
currently looks like. The terminal screen is identified by a window named 
curscr, which should not be accessed directly by the user. Instead, changes 
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should be made to stdscr (or a user-defined screen) and then refresh (or 
wrefresh) should be called to update the terminal. 


presentation space 
The array that contains the data and attributes associated with a window. 


pane An area of the display that shows all or part of the data contained in a 
presentation space associated with that pane. 


active pane =‘ The pane in which the text cursor is positioned. A pane must be active 
before you can enter information. 


| panel A group of one or more panes that are treated as a unit. The panes of a 


panel are displayed together, erased together, and usually represent a unit 
of information to a person using the application. A panel is represented on 
the display as a rectangular area that is tiled (completely filled) with panes. 


field An area in a presentation space into which the program accepts input. 


extended character 
A character other than 7—bit ASCII that can be represented in either 1 or 2 
bytes. (See dstream..) 


NLSCHAR A data type that represents a character from code page PO, P1, or P2. It is 
defined to be equivalent to unsigned short. A single NLSCHAR variable 
can contain either a 1—byte or a 2—byte character. The 1-byte characters 
are stored in the low—order byte with the high-order byte set to 0; this is the 
same way that they are stored as integers. The 2—byte characters are 
stored with the single—shift control code in the high-order byte and the 
character data code in the low-order byte. This data type has no relation to 
the NLchar data type. 


Using Screen Update Routines 
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The screen is a matrix of character positions that can contain any character from the 
character set that can be displayed on your terminal. Do not use control characters except 
when the descriptions of the library indicate that you can. The actual dimensions of the 
matrix are different for each type of terminal. These dimensions are defined when the initser 
routine calls the terminfo initialization subroutine, setupterm. The routines enforce the 
following limits on the terminal: 


Coordinate Description 


lines If the teminal specification defines less than 5 lines, the routines use a 
value of 24 lines. 


columns If the terminal specification defines less than 5 columns, the routines use 
a value of 80 columns. 


Line 0 is at the top of the screen. Line values in the routine syntax are represented by line. 
Column 0 is at the left side of the screen. Column values in the routine syntax are 
represented by col. When used in calls to the library routines, the line values come first. 


move(line, col); 


To update the screen, the routines must know what the screen currently looks like and what 
it should be changed to. The routines define the WINDOW data type to hold this information. 
This data type is a structure that describes a window image to the routines, including the 
Starting position on the screen (the (line, col) coordinates of the upper left corner) and 
size. 
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You can think of a window as an array of characters on which to make changes. Using the 
window, a program builds and stores an image of a portion of the terminal that it later 
transfers to the actual screen. When the window is complete, use one of the following 
routines to transfer the window to the terminal: 


refresh Transfers the contents of stdscr to the terminal. 

wrefresh Transfers the contents of a named window (not stdscr) to the terminal. 
ecrfp! Transfers the contents of a named panel to the terminal. 

ecrfpn Transfers the contents of a named pane to the terminal. 


This two-step process maintains several different copies of a window in memory and selects 
the proper one to display at any time. In addition, the program can change the contents of 
the screen in any order. When it has made all of the changes, the library routines update the 
terminal in an efficient manner. 


Changing Display Attributes 


Use the color and display characteristics defined in the following table for defining color and 
display attribute characters.section defining color and display attribute characteristics. The 
values of these variables depend on the capabilities of the current terminal and the priorities 
that you assign to the attributes. Change the values of these variables with the sel_attr 
routine. See the Screen Attributes Sample Program code fragment to see how to change the 


default set of attributes. 


The section entitled Attribute Byte Order lists the order that the attribute bytes are packed. 


Name Attribute 

UNDERSCORE Display characters with underline. 

REVERSE Display characters in reverse video. 

NORMAL Display characters without highlighting (return to normal). 

INVISIBLE Do not display characters. 

STANDOUT Display characters in high intensity (can be used with other attribute 
colors). On many terminals, this is the same as BOLD. 

BOLD Display characters in bold font (or high intensity on some terminals). 

BLINK Display blinking characters (can be used with other attribute colors). 

DIM Display characters in reduced intensity. 

PROTECTED Protected display field. 

F_BLACK Set foreground color to black. 

F_BLUE Set foreground color to blue. 

F_GREEN Set foreground color to green. 

F_CYAN Set foreground color to cyan. 

F_RED Set foreground color to red. 

F_MAGENTA Set foreground color to magenta. 

F_BROWN Set foreground color to brown. 

F_WHITE Set foreground color to white. 

B_ BLACK Set background color to black. 

B BLUE Set background color to blue. 

B_ GREEN Set background color to green. 

B_CYAN Set background color to cyan. 

B_RED Set background color to red. 

B_ MAGENTA Set background color to magenta. 

B_BROWN Set background color to brown. 

B_WHITE Set background color to white. 

FONTO Select defined character font 0. 

FONT1 Select defined character font 1. 

FONT2 Select defined character font 2. 
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FONT3 Select defined character font 3. 


FONT4 Select defined character font 4. 
FONTS5 Select defined character font 5. 
FONT6 Select defined character font 6. 
FONT7 Select defined character font 7. 


Attribute Byte Order 


The characteristics that a program selects for the terminal are loaded into the attribute byte 
associated with the data being displayed. Select as many of the attributes as needed, but 
those selected are packed. into the attribute byte in the following order: 


. BOLD, 

_ REVERSE 
F_WHITE 

. F_LRED 

. F_BLUE 

. F_GREEN — 
. F_BROWN 

_ F_MAGENTA 
. F_CYAN 
10.F_BLACK 
11.B_BLACK 
12.B RED 
13.B_BLUE 
14.B GREEN 
15.B_ BROWN 
16.8 MAGENTA 
17.B_CYAN 
18.B_WHITE 
19. UNDERSCORE 
20.BLINK 

21 INVISIBLE 
22.DIM 
23.STANDOUT 
24.PROTECTED 
25.FONTO 
26.FONT1 
27.FONT2 
28.FONT3 
29.FONT4 
30.FONTS 
31.FONT6 
32.FONT7 
33.NULL 


Controlling Input with the keypad, extended, and trackloc Routines 
The keypad routine allows a program to recognize contro! sequences in the input without 
searching the input or introducing device dependencies. If keypad is active, it scans all input 
data for control sequences. If it finds a control sequence, it returns the associated code to 
the program instead of the actual control sequence. The control codes are shown in the 
following table. These codes are defined in the file cur02.h with values greater than 0x100. 


OONOOAWN = 


To get international character support processing on input, extended must be active. If 
extended is turned off, shift codes and data codes input separately. 
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To get tracking of the locator cursor on the screen, trackloc must be active. If trackloc is 
turned off, the application has to handle the tracking of the locator cursor. 


Name 
KEY_NOKEY 
KEY BREAK 
KEY_DOWN 
KEY_UP 
KEY LEFT 
KEY_RIGHT 
KEY HOME 


KEY_BACKSPACE 


KEY_DL 
KEY_IL 
KEY_DC 
KEY_IC 

KEY EIC 
KEY_CLEAR 
KEY EOS 
KEY_EOL 
KEY_SF 
KEY_SR 
KEY_NPAGE 
KEY_PPAGE 
KEY_ STAB 
KEY_CTAB 
KEY_CATAB 
KEY_ENTER 
KEY_SRESET 
KEY_RESET 
KEY_PRINT 
KEY LL, 
KEY_A1 
KEY_A3 
KEY_B2 
KEY_C1 
KEY_C3 
KEY_DO 
KEY_QUIT 
KEY_CMD 
KEY_PCMD 
KEY_NPN 
KEY_PPN 
KEY_CPN 
KEY_END 
KEY_HLP 
KEY_SEL 
KEY_SCR 
KEY_SCL 
KEY_TAB 
KEY_BTAB 
KEY_NEWL 
KEY_FO 
KEY_F(n) 


Description 

No keyboard data and no delay on 
Break 

Cursor down 

Cursor up 

Cursor left 

Cursor right 

Home — top left 
Backspace 

Delete line 

Insert line 

Delete character 

Insert character mode start 
Exit insert character mode 
Clear screen 

Clear to end of screen 
Clear to end of line 
Scroll forward 

Scroll backward (reverse) 
Next page 

Previous page 

Set tab stop 

Clear tab stop 

Clear all tab stops 
Enter key 

Soft reset key 

Hard reset key 

Print of copy 

Lower left (last line) 
Pad upper left 

Pad upper right 

Pad center 

Pad lower left 

Pad lower right 

DO key 

QUIT key 

Command key 
Previous command key 
Next pane key 
Previous pane key 
Command pane key 
End key 

Help key 

Select key 

Scroll right key 

Scroll left key 

Tab key 

Back tab key 

New-line key 

Function key — 128 values 
Not used . 
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KEY_ESC1 Added to the ending character code for ESC sequences in the 
form ESC c with c in the range 0x30 — 0x7f. The value sent is in 
the range 0x200 to 0x24f. 

KEY_ESC2 Added to the ending character code for ESC sequences in the 
form ESC [sc with c in the range 0x40 — 0x7f. The value sent is 
in the range 0x250 to 0x28f. 

To use the control sequences in a program, first use a call to the keypad routine: 


keypad(TRUE); . 


Scrolling Windows 


if a window includes the lower right corner of the terminal screen, the flag byte bit, 
_SCROLLWIN, in the WINDOW structure for that window is set. This bit indicates that if a 
character is placed in the lower right corner of the window, the terminal inserts a blank line at 
the bottom of the screen (scrolls) to make room for more information. lf a program defines 
the window with scrollok to allow it to scroll and place a character in the lower right corner 
of the window, the routines automatically call the scroll routine. 


lf a program does not define the window with scrollok, scrolling is not allowed. When a 
character is placed in the lower right corner of the window, the routines reset the current col 
coordinate to zero (beginning of line) and does not scroll. 


To move a window to the lower right corner, use the mvwin routine. The SCROLLWIN flag 
bit for that window is not automatically set. However, the wrefresh routine handles that 
window as if the SCROLLWIN flag bit were set. 


Improving Performance 


To speed up output, create an output buffer using statements similar to the following 
program fragment: 


#include <stdio.h> 
char obuf[BUFSIZE]; 
main( ) 


setbuf (stdout, obuf); 


/* rest of program */ 


How to Write to a Window 


Procedure 


1. Use the following functions to change the contents of a window: 


addch(c) 

addstr(str) 

box(win, vert, hor) 
cbox(win) 
chgat(num_chars, mode) 
clear 

clearok(scr, boolf) 
cirtobot 
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clrtoeol 

colorend 
colorout(mode) 
delch 

deletein 

ecactp 

ecshpl 

ecrfpl 

ecrfpn 

ecrmpl 

ecrmpn . 

erase 

fullbox(win, vert, hor, topl, topr, botl, botr) 
insch(c) 

insertin 

move(line, col) 
overlay(wint, win2) 
overwrite(wint, win2) 
printw(fmt, arg1, arg2, ...) 
refresh 

standend 

standout 

waddfid 


. Use the refresh routine to transfer the contents of the current window to the screen after 


all changes to the window are complete. The refresh routine does not rewrite any part of 
the window that has not changed since the last refresh call. To force the whole window to 
be rewritten, use the touchwin routine before the refresh routine. Also use ecrfpn to 
refresh a pane, and ecrfpl to refresh a panel. 


How to Control the Screen 


Procedure 


. Use the following library routines to control and manipulate the windows, panes, and 


panels on the screen: 


delwin(win) 

ecadpn 

ecaspn 

ecbplis 

ecbpns 

ecdfpl 

ecdppn 

ecdspl 

ecdvp! 

ecrip! 

endwin 

gettmode 

getyx(win, line, col) inch 
initscr 

leaveok(win, boolf) 
longname 
mvcur(lastline, lastcol, newline, newcol) 
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mvwin(win, line, col) 

newview(orig_win, num_lines, num_cols) 
newwin(lines, col, begin_line, begin_col) 

ni 

nonl 

resetty 

savetty 

scroll(win) 

scrollok(win, boolf) 

setterm(name) 

subwin(win, lines, cols, begin_line, begin_col) 
touchwin(win) 

trackloc 

tstp 

unctri(ch) vscroll(view_win, deltaline, deltacol) 
vscroll(view_win, deltaline, deltacol) 





How to Define Panels and Panes 
Procedure 
1. To define a panel, provide the following information about the panel: 
e The size of the panel as it appears on the display. 
e The location on the display of the upper left corner of the panel. 
e Whether the panel is to have a border. 
e How the panel is to be divided into panes. 
2. To define a pane within a panel, provide the following information: 
e The size of the presentation space associated with the pane. 
e The relative size of the pane within the panel. 
e Whether the pane is to have a border. 
e lf and how the pane is to be further divided into smaller panes. 


3. To divide panels and panes into smaller panes, follow a few simple rules. These rules 
ensure that a program can access all areas on the panel or pane that it creates: 


e You can divide a panel or pane either horizontally (using a horizontal dividing line) or 
vertically (using a vertical dividing line). 


e Panes created by a horizontal division must be linked together from top to bottom. 
e Panes created by a vertical division must be linked together from left to right. 


e Panes that are divided again must be linked to the first pane of its subpanes. The 
original pane in this case is not a part of the presented panel, but it is needed to define 
the structure of the panel. 


e Panes created by a horizontal division have a fixed horizontal dimension that is the 
same as its parent pane. 


e Panes created by a vertical division have a fixed vertical dimension that is the same as 
its parent pane. 
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e Specify the variable dimension for a pane as being in one of three categories: 


Fixed For a fixed pane, specify the number of rows or columns, including 
any border, to assign to the pane. 


Fractional For a fractional pane, specify the percentage of the available space to 
assign to the pane. 


Floating For a floating pane, do not specify a size. The floating pane shares 
the available space equally with any other floating panes that the 
program creates. 


The linkage of the panes forms a tree structure. The root of the tree is a panel 
description. All other elements in the tree are pane descriptions. 


How to Create Panels and Panes 


Procedure 


To create a panel, perform the following steps: 


1. 
2. 


Define panel P using the ecbpls routine with a link to pane A. 


Divide the panel (P) with two horizontal splits into three panes. Use the ecbpns routine to 
define the three panes with the following links: 


a. A—No links 
b. B—Linked to A and D 
c. C—Linked to B and F 


Divide pane B with a single vertical split into two panes. Use the ecbpns routine to define 
the two panes with the following links: 


a. D—No links 
b. E—-Linked to D 


Divide pane C with two vertical splits into three panes. Use the ecbpns routine to define 
the three panes with the following links: 


a. F—No links 
b. G-— Linked to F 
c. H—Linked toG 


The following diagrams show the final panel appearance after the preceding steps have 
been completed. Links in the Panel and Pane Structure, and Creating Panes in the Panel. 
Horizontal lines show the links within a pane; vertical lines show links to the parent panel or 
pane. 
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Creating Panes in the Panel 


IE 


Links in the Panel and Pane Structure 





Example Panel Final Appearance 





The following is a Sample Program from which the Final Panel was created: 
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#include <cur01.h> 
#include <cur05.h> 


main() 


{ 


panel *P ; 


initscr () ; 


A 


ecbpns (24,80,NULL,NULL,0,2500,Pdivszp,Pbordry NULL,NULL); 


ecbpns (24,80,NULL,NULL,0,0, Pdivszf,Pbordry,NULL,NULL) ; 
ecbpns (24,80,D, NULL,0,0, Pdivszf,Pbordry,NULL,NULL) ; 


ecbpns (24,80,A,D, Pdivtyh,3000, Pdivszf,Pbordry,NULL,NULL) ; 


ecbpns (24,80,NULL,NULL,0,0, Pdivszf,Pbordry,NULL,NULL); 
ecbpns (24,80,F, NULL,0,5000,Pdivszf,Pbordry,NULL,NULL); 
ecbpns (24,80,G, NULL,0,3000,Pdivszf,Pbordry,NULL,NULL) ; 


ecbpns (24,80,B, F,Pdivtyh, 0, Pdivszf,Pbordry,NULL,NULL); 


ecbpls (24,80,0, 0,NULL, Pdivtyv, 0, Pdivszf,Pbordry,A ); 


ecdvpl ( P ); 
ecdfpl ( P, FALSE ); 
ecshpl ( P ); 
ecrfpl ( P ); 


endwin(); 


} 


/* end main program */ 


How to Use the Extended Curses Library 


Procedure 


1. 


To use the library, define the types and variables that the routines use. The file cur01.h 
contains all of the definitions that are needed for the library routines for most common 
uses. Include this file in the program by putting the following statement at the top of the 
program source: 


#include <cur0l.h> 


. To use the library routines for panel and pane management (those routine names begin 


with the letters ec), use the following statement in the program source to include a larger 
set of definitions: 


#include <cur05.h> 


. To use the library routines for programs that use global variables defined to represent the 


information taken from the terminal file, include the following statement in the program 
source: . 


#include <cur00.h> 
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The cur00.h header file also contains include statements for the following header files: 
Stdio.h, sgtty.h, and cur01.h, but you do not have to specify these header files 
separately in the program. 


4. To compile a program with the cc command, specify the two additional libraries on the 
command line: 


cc myproc.c —lcur 


The above example compiles the program myproc.c, with the linked output going to 
a.out. 





How to Set Up the Extended Curses Environment 


Procedure 
To use the library routines, the program must set up the operating conditions for the 
program. Perform the following actions in the program, if they apply, in the order that they 
appear: 


1. Perform all necessary actions to load the program and make sure that it is operating 
successfully. 


2. To change the defined size of the terminal, set the variable LINES and COLS to new 
values. 


3. Use the routine initser to get information about terminal characteristics, and to allocate 
memory for stdser and curscr. Cail initscr before calling any routines that affect 
windows. If the program uses a window routine before initscr, the program will not run. 


4. Check the value that initscr returns to see if the screen setup was successtul. If this 
value is 0 (FALSE or ERR), then initscr could not get enough memory for the needed 
windows. 


Use any needed terminal status changing routine, such as nj or crmode. 
Create any new windows with the newwin or subwin routine. 


Create panels using ecbpls, ecbpns, or ecdfpl. 


OND a 


Define or change the characteristics of the windows as needed. For example, the routine 
scrollok allows the window to scroll, or the routine leaveok leaves the cursor at the 
position of the last change. 


The program can now work with the windows that it has detined. When the program is done, 
use the routine endwin to clean up before exiting the program. This routine restores 
terminal modes to what they were when the program first started. 


Curses Programming Example 


The following example program, twinkle.c, uses the extended curses library routines 
(libcur.a) to create a series of displays on the screen. 


#include <cur00.h> 
#include <signal.h> 


#define NCOLS 80 
#define NLINES 24 
#define MAXPATTERNS 11 
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struct locs 


{ 
char y, X;} 


}; 
typedef struct locs lLOCS; 


LOCS layout{ NCOLS * NLINES }]; /* current board layout */ 


int pattern, /* current pattern number */ 
numstars; /* numbers of stars in ptern */ 
main () 
{ 
char *getenv(); 
int die(); 
srand( getpid() ); /* initialize random sequence */ 
initscr(); 


Signal( SIGINT, die ); 
noecho(); 

leaveok( stdscr, TRUE ); 
scrollok( stdscr, FALSE ); 


for( ;; ) 
{ 
makeboard(); /* make the board setup */ 
puton( ‘*’ ); /* put on '*'s */ 
system( "sleep 2” ); 
erase(); 
refresh(); 
} 
} 
/* 


** On program exit, move the cursor to the lower left corner by 
** direct addressing, since current location is not certain. 

** We say we used to be at the upper se corner to obtain 

** absolute addressing. 

*/ 


die() 


signal( SIGINT, SIG_IGN ); 
mvcur( LINES/2, COLS/2, 0, 0 ); 
wcelear( curscr ); 
wrefresh({ curscr ); 
endwin(); 
exit(0); 

} 


/* 

** Make the current board setup. It picks a random pattern and 
** calls ison() to determine if the character is on that pattern 
** or not. 


set 


makeboard( ) 
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reg int y, xX; 
reg LOCS *lp; 


pattern = rand() % MAXPATTERNS; 
lp = layout; 
for( y = 0; y < NLINES; yt++ ) 


{ 
for( x = 0; x < NCOLS; x++ ) 
if( ison( y, x )) 
{ 
Ip—- yy; 
lp++ —> x = x; 
} 
} 
} 
numstars = lp — layout; 
} 
/* 
** Return TRUE if( y, x ) is on the current pattern. 
*/ 


ison( y, xX ) 
reg int y, x; 


{ 
switch( pattern ) 
{ 
/* 
** Alternating lines: 
*/ 
case 0: 
return !( y & O1 ); 
/* 
** Box: 
*/ 
case 1: 
if( y <3 || y >= NLINES — 3 ) 
return TRUE; 


return( x < 4 || x >= NCOLS — 4 ); 
/* 
** Cross: 
* / 
case 2: 
return( ( x ty ) & O1 ); 
/* 
** Bar across center: 
*/ 
case 3: . 
return( y >= 9 && y <= 15 ); 
/* 
** Alternating columns: 
*/ 
case 4: 
return !( x & 02 ); 
/* 


** Bar down center: 
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* / 
case 5: 
return( x >= 36 && x <= 44 ); 
/* 
** Bar across and down center: 
*/ 
case 6: 
return( ( y >= 9 && y <= 15 ) || ( x >= 37 && x <= 43 )); 
/* 
** Bar across and down center, in a box: 
*/ 
case 7: 
if( y < 3 || y >= NLINES — 3 ) 
return TRUE; 
if( x < 4 || x >= NCOLS — 4 ) 
return TRUE; 
return( ( y >= 10 && y <= 14 )||( x >= 36 && x <= 44 )); 
/* 
** Asterisk: 
*/ 
case 8: 
if( abs( x ~ y ) <= 2 || abs( NLINES — ( x + y )) <= 2 ) 
return TRUE; 
if( abs( ( NLINES/2 ) — x ) <= 2 ) 
return TRUE; 
return( abs( ( NLINES/2 ) —y ) <= 1 && x <= NLINES ); 
/* 
** Ellipse: 


*/ 
case 9: 
return 
( 
(( float ) (( x-40 ) * ( x-40 )) ) / 1521 + 
(( float ) (( y—-12 ) * ( y—-12 )) ) / 121 
) <= 1 
); . 
/* 
** Circle: 
*/ 
case 10: 
return 


( 


(( float ) (( x-28 ) * ( x-28 )) 
(( float ) (( y-12 ) * ( y-12 )) 
<= 1 


) / 729 + 
Y/-420 
) 
)i 
/* end of switch( pattern ) */ 


} /* not reached */ 
puton(ch) 
reg char ch; 
{ 
reg LOCS *lp; 
reg LOCS *end; 
LOCS temp; 
reg int Yr 
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end = &layout{ numstars ]; 
for( lp = layout; lp < end; lp++ ) 


{ 
r = rand() % numstars; 
temp = *lp; 
*lp = layout[ r ]; 
layout[ r J] .= temp; 

} 


for( lp = layout; lp < end; lpt+ ) 


mvaddch( lp —> y, lp —> x, ch ); 
refresh(); 


} 
} /* end of twinkle */ 


Screen Attributes Sample Program 


The following is a sample code fragment showing how to use the display constants to 
change the default set of attributes: 


#include <cur00.h> 
#include <cur03.h> 


int attrs[] = 

{ 
_GBOLD, _dBLINK, 
_GF WHITE, dF_RED, _dF_ BLUE, _dF GREEN, 
_dF_ BROWN, _dF MAGENTA, _dF_CYAN, _dF_ BLACK, 
_dB BLACK, _dB RED, _dB BLUE, _dB GREEN, 
_dB BROWN, _dB MAGENTA, dB CYAN, _dB WHITE, 
_GREVERSE, _dINVISIBLE, _dDIM, _dUNDERSCORE, 
NULL 

}} 


main( ) 


{ 


sel_attr(attrs); 

initser( ); 

if( REVERSE == NORMAL ) REVERSE = F_BLACK | B_WHITE; 

if( INVISIBLE == NORMAL ) INVISIBLE = F_BLACK | B_ BLACK; 
if( DIM == NORMAL ) DIM = F_BLACK | BOLD; 

if( UNDERSCORE == NORMAL ) UNDERSCORE = F_WHITE | B_RED; 
STANDOUT = REVERSE; 


<rest of program> 


endwin( ); 
} /* end main */ 


The routines only define 8 bits of unique attribute information. Selecting foreground color, 
backrgound color or font requires either 1, 2 or 3 bits depending upon the number of colors 
or fonts in the list. 1 bit for 2 or fewer, 2 bits for 3 or 4, and 3 bits for 5 to 8. Each character 
attribute takes 1 bit. However, the attribute names passed to wcolorout are variables, so 
that you can make combinations from the other attributes as shown in the last part of the 
preceding sample program. If a requested attribute (that is not the terminal default) is equal 


6-18 AIX User Interface Programming Concepts 


to NORMAL, then it is either not supported by the terminal, or there is not enough space in 
the window structure for its mask. 
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Index 


Symbols 


.c file, class record variable, structure initializer for, 
5~158—5-—160 

$HOME/.mwmic file, contents of, 2—2 

/usr/include/Xil/cursorfont.h directory, defining 
cursors in, 5-267—-5-270 


A 


accelerators, use of, 5-200 
action dialog box, purpose of, 4—58 
action names, translating to procedures, 5-199 
action sequence, use of, 5-200 
action tables, description of, 5-198 
aimterm command, datastream support, 
5-262—5-—267 
AlXDeviceMappingNotify events, processing, 5-147 
AlXFocus events, processing, 5-145—5-—147 
AlXwindows , 
interactive objects 
XmGadget class, 3-4 
XmPrimitive class, 3—4 
top-level class hierarchy, illus., 3-4 
AlXwindows Desktop, customizing of, 1-1—-1-—40 
AiXwindows environment 
applications, use of, 4—4 
elements of, 4—3 
input selection model, 4-3 
window manager, use of, 4—4 
AlXwindows gadgets 
adding callback routines, 3-24—3-38 
realizing, 3-27—3~38 
AlXwindows interface, adding top—level windows, 
3-22—3-38 
AlXwindows menus, functions, common to, 4-43 
AlXwindows selection model 
auto—selection action, 4-22 
contiguous objects, range selection of, 4-17 
controls, examples of, 4-25 
keyboard operations, illus., 4-16 
mouse button operations, illus., 4-16 
non—contiguous objects, selection of, 4-19 
non—contiguous selection using keyboard, 
Steps in, 4~21 
non—continguous selection using the mouse, 
steps in, 4~20 
object, deselection of, 4-21 
objects, default actions, 4-21 
one object selection, 4-16 
range selection with a keyboard, steps in, 4-19 
range selection with a mouse, steps in, 4-18 


single selection with a keyboard, steps in, 4-17 
single selection with a mouse, steps in, 4-17 
AlXwindows Toolkit 
metaclasses 
Object, 3-4 
RectObject, 3-4 
WindowObj, 3-4 
naming conventions 
callback reason, 3-2 
define name, 3-2 
Enhanced X-Windows subroutine, 3-2 
gadget class name, 3-2 
gadget class pointer, 3-2 
include directory, 3-2 
include filenames, 3-2 
library with include directory, 3-2 
prefixes, 3~1 
resource class, 3—2 
resource name, 3-2 
subroutines, 3-2 
suffixes, 3-2 
widget class name, 3-2 
widget class pointer, 3~2 
purpose of, 3—1 
subroutines, categories of, 3-3 
AlXwindows toolkit 
creating an application interface, 3-18—3-—38 
creating gadgets, 3—-26—-3-38 
creating menu systems, 3-38—3-40 
creating widgets, 3-26—3-—38 
description of, 4-1 
including interfaces, 3-20—3-38 
linking libraries, 3-28—3-38 
providing resource default files, 3~-29-—-3~—38 
AlXwindows widgets . 
adding callback routines, 3-24—-3-38 
realizing, 3-27—3-38 
AlXwindows window manager 
components of, 4-6 
description of, 4—1 
application, input loop, processing of, 5-189 
application interface 
initializing Enhanced X-Windows toolkit, 
3-—21—3-38 
listing include files, 3-20—3-38 
steps to create, 3-18—3-38 
application shell instance, creating, 5-165 
application title, location of, 4~—9 
application window, extending the lifetime of, 5-52 
applications 
automatic decryption, 1-3 
automatic encryption of, 1-3 
background mail server, 1-3 


Index X—1 


changing environments, 1-3 
consistency, explanation of, 4-2 
data files, associating with programs, 1-3 
exiting, 5-169 
files, identifying the user with icon colors, 1-3 
flexibility, use in, 4—3 
irreversable actions, response to, 4—3 
operational models, examples of, 4-10 
product 
base of, 4-63 
localization portion, 4-63 
simulating familiar environments, 1-2 
trash icon, 1-3 
user—object interaction, use in, 4—2 
ApplicationShell widget class, description of, 5-179 
arcs, drawing, 5-40 
areas 
clearing, 5~39 
copying, 5-39 
filling rectangular, 5-41 
argument lists 
creating, 5-164 
merging, 5-164 
arguments 
sending, 5—-139—5-—140 
variable length, use of, 5-140 
atoms 
predefined, values of, 5-253 
use of, 5-50 
attributes, description of window, 5-56 
auto tabbing, use of, 4-34 
automatic entry, description of, 4—37 
automatic scrolling, 4-36 


backing_store field 
Always value, 5-68 
NotUseful value, 5-68 
WhenMapped value, 5-68 
behavior resource, controlling window policies, 2—4 
bit_gravity field 
ForgetGravity value, 5-66 
StaticGravity field, 5-66 
bitmaps 
associating with a name, subroutines for, 3-13 
defining, 5-37 


C 


.c file, class record variable, structure initializer for, 
5-158—5-—160 
call, blocking occurence, 5-2 
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callback lists, subroutines, performing operations 
involving, 5-169-—5—170 
callback routines 
adding for AlXwindows gadgets, 3-24—3-38 
adding for AlXwindows widgets, 3-24—3-38 
callbacks, use of, 5—-169—5-—1 70 
cap_style field 
concident endpoints, drawing, 5-77 
values of, 5-79 
cascading menu 
advantages of, 4—40 
description of, 4-38 
characters 
drawing text, 5-42 
interpretation of, 2-2 
check buttons, parts of, 4-31 
child, managing the geometry of, 5-184 
child window, description of, 5—1 
CirculateNotify events, reporting to clients, 5~25 
CirculateRequest events, reporting to clients, 5-28 
click-to—type. See explicit focus policy under input 
focus model 
client, application programs, relationship to, 
5—1—5-3 
client area, location of, 4-9 
client areas 
beginning, criteria for, 4-27 
size, adjustment of, 4-28 . 
client controls, description of, 4-24 
client subareas, description of, 4-22 
ClientMessage events, generating when client calls 
XSendEvent subroutine, 5-29—-5-32 
clip_x_origin field, description of, 5-80 
clip_y_origin field, description of, 5-80 
clipboard, modifying, subroutines for, 3-12 
collating sequences, description of, 4-63 
colormap 
determining resident, 5-36 
reading entries in, 5-36 
reporting changes in state of, 5-29 
using standard atoms, 5-35 
using standard properties, 5-35 
colormaps 
allocating, 5-34 
creating, 5-33 
mapping of, 5-34 
using, 5-35 
Command dialog box, purpose of, 4—59 
command line 
description of, 4-23 
parsing options from a C language, 5—49 
Command widget, functions of, 5-198 
commands, specifying for the AliXwindows desktop 
using ac keyword, 1—23—1-34 
using actions keyword, 1-23—1-—34 
Composite class, resources, providing to subclasses, 
3-5 


Composite widget class 
defining, 5-154 
purpose of, 5-152 
composite widgets 
adding children to, 5-174 
composite editor, duties of, 5-173 
deleting children of, 5-175—5—178 
inserting children in, 5—-174—5-175 
managed set 
adding to, 5-173 
adding widgets to, 5-175 
mapping a, 5-173 
removing from, 5-173 
removing widgets from, 5-175 
managed state, determination of, 5-176 
purpose of, 5-173—5-—174 
removing children from, 5-176 
resizing children of, 5-175 
verifying the class of, 5-174 
XtCreateWidget subroutine, use of, 5-173 
XtDestroyWidget, use of, 5-173 
compound strings 
creating, subroutines for, 3-11 
manipulating, subroutines for, 3-11 
configFile resource, window management resource 
description file, 2-2 
configuration items, format of, 1-35 
ConfigureNotify events, reporting to clients, 
5—25—5-26 
ConfigureRequest events, reporting to clients, 5-28 
connections 
closing, 5—-259—5-—260 
controlling flow, 5-260 
internal concurrency, 5-260 
Constraint class, resources, providing to subclasses, 
3-5 
constraint data, deallocating dynamic, 
5—168—5-—169 
Constraint widget class 
defining, 5-154—5-—155 
purpose of, 5-152 
constraint widget instance, initializing, 5-166 
constraint widgets 
allocating, 5-177 
deallocating, 5-177 
initializing, 5-177 
maintaining, 5-177 
use of, 5-176—5-—177 
context manager, description of, 5-49-—5—50 
control panels 
description of, 4-27 
use of, 4—23 
controls 
choosing the appropriate, 4-28 
columns, aligning of, 4—29 
combining, 4-26 
examples of, 4-37 
dialog boxes, advantages of, 4-29 
grouping similar functions, 4—25 


making unavailable, 4-53 

menus, advantages of, 4—29 

multiple, methods of, 4-26 

pop—up menus, advantages of, 4-28 

push buttons, advantages of, 4-28 

scanning order, use of, 4-28 

sequence of use, 4-28 

types of, 4-30 
convenience creation subroutines, list of, 3-10 
Core class, metaclasses in, 3-4 
Core widget class 

defining, 5-153—5—154 

purpose of, 5-152 
CreateNotify events, reporting to clients, 5-26 
creation subroutines, list of, 3-9 
curses, setting terminal-dependent variables, 6—2 
curses library 

cur01.h file, 6-13 

how to use, 6—-13-—-6—14 

initializing, 6—1 

pane, management of, 6-13 

panels, management of, 6-13 

terminal file, global variables, 6-13 
cursor, navigation, default keys for, 4—68 
cursors 

list of, 5-267—5-—270 

manipulating, 5-42 

shapes of, illus., 4-34 


D 


da keyword, 1-26—1-34 

dashes field, description of, 5-81 

data, country-specific formats, 4-64 

data structures 
_XExtCodes, example of, 5-148 
ApplicationShellClassRec, 5-221 
ApplicationShellPart, 5-225 
ApplicationShellWidget, 5-227 
CompositeClassPart, fields in, 5-213 
CompositePart, fields in, 5-214 
ConstraintClassPart, fields in, 5-214 
ConstraintPart, fields in, 5-214 
CoreClassPart, fields in, 5-210 
CorePart 

default values for, 5-212 
fields in, 5-211 

locking, 5-139 
OverrideShellClassRec, 5-220 
OverrideShellPart, 5-223 
OverrideShellWidget, 5-225—-5-226 
ShellPart, 5-222—5-—223 
ShellWidget, 5-225 
TopLevelSheliClassRec, 5-221 
TopLevelShellPart, 5-224—5—225 
ToplevelShellWidget, 5-227 
TransientShellClassRec, 5-221 
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TransientShellPart, 5-224 
TransientShellWidget, 5-226 
VendorShellClass, 5-220 
VendorShellPart, 5-224 
VendorShellWidget, 5-226 
WMShellClassRec, 5-220 
WMShellPart, 5-223—5-224 
WMShellWidget, 5-226 
XAIXDeviceMappingEvent, description of, 
5-133 
XAnyEvent, description of, 5—96 
XArc, description of, 5-85 
XChar2b, description of, 5~86—5—87 
XCharStruct 
description of, 5-85—5-—86 
fields of, 5-85 
XCirculateEvent, description of, 5-111 
XCirculateRequestEvent, description of, 
5-118—5-119 
XClassHint, description of, 5-131 
XClientMessageEvent, description of, 
5-122—5-123 
XColor 
description of, 5—-75—5—76 
fields of, 5-75 
XColormap, description of, 5-121—5—122 
XConfigure Event, description of, 
5-112—5-113 
XConfigureRequestEvent, description of, 
5-119-—5-120 
XCreateWindowE vent, description of, 5-113 
XCrossingEvent, description of, 5—-104—5-106 
XDestroyWindowEvent, description of, 
5-113—5-114 
XEnterWindowE vent, description of, 
5—104—5-—106 : 
XErrorEvent, description of, 5-126 
XEvent, description of, 5-97 
XExposeEvent, description of, 5-108 
XFocusChange, description of, 5—106—5-—107 
XFocusinEvent, description of, 5—-106—5-—107 
XFocusOutEvent, description of, 
5~—106—5-—107 
XFontProp, description of, 5-86 
XFontStruct 
description of, 5-87—-5-—90 
fields of, 5~87—-5—95 
XGCValues 
description of, 5-76—5-—82 
fields of, 5-78 
XGraphicsExposeE vent, description of, 
5-109—5-110 
XGravityEvent, description of, 5-114 
XHostAddress 
description of, 5-95 
fields of, 5-95 
XiconSize, description of, 5-130—5—131 
Ximage, description of, 5-92 
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XKeyboardConirol 
description of, 5-93—-5-—94 
fields of, 5-93 
XKeyboardState, description of, 5-94 
XKeymapEvent, description of, 5-107—5—108 
XKeyPressedEvent, description of, 
5—100—5-101 
XLeaveWindowE vent, description of, 
5~—104—5-106 
XMapEvent, description of, 5-115 
XMappingEvent, description of, 5-115—5~—116 
XMapRequestEvent, description of, 5-120 
XModifierKeymap, description of, 5—94 
XNoExposeE vent, description of, 5-110 © 
XPointData, description of, 5-84—5-—85 
XPointerMovedEvent, description of, 5-102 
XPropertyEvent, description of, 5-123 
XRectangle, description of, 5-84 
XReparentEvent, description of, 5-116—5—117 
XResizeRequestEvent, description of, 5-121 
XrmOptionDescList, description of, 
5—132—5-—133 
XrmValue, 5-235 
description of, 5-131 
XSegment, description of, 5-84 
XSelectionClearEvent, description of, 5-124 
XSelectionEvent, description of, 5-125 
XSelectionRequestEvent, description of, 
5—124—5-—125 
XSetWindowAttributes 
background_pixel field, 5-65 
background_pixmap field, 5-64 
backing_pixel field, 5-69 
backing_planes field, 5-68 
backing_store value, 5-68 
bit_gravity field, 5-66 
border_pixel field, 5-65—-5—66 
border_pixmap field, 5—-65 
colormap field, 5-70 
cursor field, 5-70 
description of, 5-63—5—70 
do_not_propagate_mask field, 5-69 
event_mask field, 5-69 
override_redirect field, 5-69 
save_under field, 5-69 
win_gravity field, 5-67 
XSizeHints, description of, 5—129—5—130 
XStandardColormap 
description of, 5-83—5-—84 
fields in, 5-83—5—84 
XtActionList, example of, 5—236 
XtArgVal, purpose of, 5-215 
XtCallbackList, description of, 5-217 
XtConvertArgRec, 5-236 
XTextltem, description of, 5-90-—5-91 
XTextiltem16, description of, 5-91 
XtGeometryResult, 5-230 
XtPopdowniD, example of, 5-240 


XtResource, 5-232—5—234 
XtWidgetGeometry, 5-229 
XUnmapEven, description of, 5-117 
XVisibilityEvent, description of, 5-118 
XVisuallnfo 
description of, 5-61—5-63 
fields of, 5-61 
XWindowAttributes, fields of, 5-73—5—75 
XWindowChanges, description of, 5-70-—-5—72 
XwindowChanges, fields of, 5-70 
XWindowsAttributes, description of, 
5-73—5-75 
XWMdHints, description of, 5-127—5-—128 
dates, format of, 4-64 
dd keyword, 1-25—1-34 
defaults, use of, 4-29 
Desktop 
appearance, configuring of, 1-13 
configuration, editing resources, 1-13 
creating menus, procedure of, 1-10—1—40 
editing menus, procedure of, 1—-10—1—40 
functioning, configuring of, 1-13 
resource mechanism, functions of, 1-1 
desktop 
command language, format of, 1-43 
description of, 4—5 
layout keyword, 1-24—1-34 
specifying icons to be locked on 
using If keyword, 1-31—1-34 
using lock_on_desktop keyword, 1-31 
Desktop directory, defining icon behavior, procedure 
of, i-7—1—40 
destroy callbacks 
adding, 5-168 
deleting, 5-168 
DestroyNotify events, reporting to clients, 5-26 
dial device, processing input focus events, 5-145 
dial device, processing events, 5—-143—5-145 
dialog box 
Action selection, 4-54 
application modal, description of, 4-54 
Apply selection, 4-54 
Cancel selection, 4—54 
Close selection, 4—54 
controls, operation of, 4-54 
default buttons, use of, 4-56 
description of, 4-25, 4-27, 4-53 
ending, 4-53 
Help selection, 4-54 
location, determining, 4-61 
message, types of, 4-56 
navigating through, 4-61 
No selection, 4-54 
OK selection, 4-54 
purpose of, 4-53 
push buttons, use in, 4-55 
Reset selection, 4-54 
Retry selection, 4-54 
size, determining, 4—61 


starting, 4-61 
Stop selection, 4-54 
system—modal, description of, 4—54 
Text selection, 4-54 
Yes selection, 4-54 
dialogs, creating through desktop utilities, procedure 
of, 1-13—1—40 
directory window, defining the effect of dropping 
icons into, using drop_in_action keyword, 
1-26—1-34 
directory windows, specifies actions to be performed 
upon trigger, using directory_rules keyword, 
1-25—1-34 
directory_rules keyword, 1-25—1-34 
display 
closing, information on, 5-11 
opening, information on, 5-10 
drawables, description of, 5-2 
drop_in_action keyword, 1-26—1-—34 
dt keyword, 1-24—1-34 


E 


Edit menu 
Clear selection, 4-47 
Copy selection, 4-47 
Cut selection, 4-47 
Delete selection, 4-47 
Paste selection, 4—47 
selections in, 4—46 
Undo selection, 4-46 

Enhanced X-Windows 
AIX operating system, relationship to, 5-1 
data structures, list of, 5-60 
screen, support for, 5—1 

Enhanced X-Windows subroutines, functional list of 
changing window attributes, 5-3 
clearing and copying areas, 5—-5—-5—10 
communicating with window managers, 5-8 
controlling the screen saver, 5—7 
creating and destroying windows, 5-3 
creating and freeing pixmaps, 5-4 
drawing lines, 5-5—5-—10 
drawing text, 5-6 
enabling or disabling synchronization, 5-8 
filling areas, 5—-5—-5—-10 
handling default geometry color, 5-9 
handling events, 5-7 
handling window manager functions, 5-6 
keyboard event functions, 5-8 
loading and freeing fonts, 5-5 
manipulating bitmaps, 5-10 
manipulating color cells, 5-4 
manipulating colormaps, 5-4 
manipulating cursors, 5-6-—-5-—10 
manipulating graphics contexts, 5-4—-5—10 
manipulating hosts and access control, 5-7 
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manipulating images, 5—9 
manipulating keyboard settings, 5-7 
manipulating regions, 5-9 
manipulating window properties, 5-4 
manipulating windows, 5-3 
obtaining window information, 5-3 
opening and closing displays, 5—3 
properties and atoms, 5—4 
querying character string sizes, 5-6 
querying visual types, 5-9 
setting window selections, 5—4 — 
transfering images, 5-6 
using cut and paste buffers, 5-9 
using default error handlin, 5-8 
using the context manager, 5-10 
using the resource manager, 5-10 
Enhanced X-Windows Toolkit 
application programming, provisions for, 5-151 
header files, 5-151—5-155 
purpose of, 5—150 
widget programming, provisions for, 5-151 
Enhanced X—Windows toolkit, initializing, 
3-21—3-38 
enter events, compressing, 5-187 
entry, processing a normal, 5-19—-5-—20 
entry boxes 
parts of, 4—32 
pre—formatting of, 4-34 
environment, obtaining defaults, 5-50 
error handler, handling the default, 5-31—5-32 
errors, handling, 5-209 
event 
defining the structures of, 5-142 
generating, 5-260 
repainting a window, 5-2 
event categories, event type table, 5-13 
event handler, remove without selecting events, 
5-191 
event handlers 
calling, 5-190 
registering with the dispatch mechanism, 
5-191 
event loop, description of, 5~12 
event manager 
description of, 5—-186—5-—191 
examining events, 5—-188—5-~—191 
reading events, 5—-188—5-—189 
event mask, retrieving, 5-191 
event masks 
description of, 5-14 
event types, table of, 5-143 
use of, 5-142 
event queue, handling, 5-31—5-32 
event sequence, description of, 5-199 
event sources 
adding, 5-186 . 
deleting, 5-186—5-191 
event structures, defining, 5-14—5-32 
event type, abbreviations of, 5—205 
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event types 

definition of, 5-13 

examples of, 5-207—5-—208 

values of, 5-204—5-205 
events 

constraining, 5-187—5~—188 

dispatching to widgets, 5-189 

managing of, 5-186 

origin of, 5—1 

queuing of, 5-2 

selecting, 5-30 

using a predicate procedure, 5-31 

exit, processing a normal, 5-19—5-—20 
expose events, processing, 5-24 
exposure event, compressing, 5-187 
exposure events, merging into a region, 5—208 
extended curses, functions, provision for, 6-2 
extended curses library, C language routines in, 6-3 
extension events, types of, 5~141—5-—142 
extensions 

description of, 5-134 

dial device, 5-142—5-143 

Ipfk device, 5-142—5-—143 

protocol requests for, 5-134 

tablet device, 5-142—5-—143 


F 


file, property atoms in, 5-89—5-—90 
File menu 
Exit operation, 4-46 
New operation, 4—45 
Open operation, 4—45 
Print operation, 4—45 
Save As operation, 4-45 
Save operation, 4—45 
selections, groups of, 4—44 
selections in the, 4—45 
file names, referring to, 1-21 
File Selection dialog box, purpose of, 4-58 
files 
describing position on the desktop 
using desktop layout keyword, 1-24—1-34 
using dt keyword, 1-24—1-34 
describing the appearance of, using icon_rules 
keyword, 1-27 
describing the behavior of, using icon_rules 
keyword, 1-27 
fill_style, description of, 5-80 
focus event 
processing when generated by grabs, 
5-24—5-32 
processing while grabbed, 5-21—5-—24 


fonts 
changing, procedure of, 1-15—1—40 
list manipulation, subroutines for, 3-15 
manipulating, 5-41 

function contexts, mwm functions, availability of, 2-3 


G 


gadget classes, hierarchy of, 3-1, 3-3 
gadgets 
creating, prerequisite tasks for, 3-26—3-38 
description of, 3-3 
setting up parameter lists for, 3-23 
widgets, differences between, 3—4 
gain ratio, description of, 4-15 
GC, caching, 5-135 
geometry 
handling preferred, 5-185 
initiating changes, 5-182 
management of, 5-174, 5-182 
managing changes, 5-184 
geometry manager ; 
caching the reply, 5-184 
changing the geometry of a child, 5-183 
duties of, 5-173 
functions of, 5-183 
making requests, 5-183 
requesting from a child, 5-184 
geometry request, compromise, use of, 5-184 
get subroutines, communicating with window 
managers, 5—43—5—44 
graphics, batching, use of, 5-135 
graphics context, manipulating, 5-37—-5-39 
Graphics Contexts, sharing, 5-208 
graphics operations, resources, use in, 5-33 
graphics resource subroutines, description of, 5-33 
GraphicsExpose events, reporting to clients, 5-25 
GravityNotify events, generating ConfigureNotify 
events, 5-72 
gravitynotify events, reporting to clients, 5-26 
grouped controls 
illus., 4-26 
push buttons, guidelines for, 4-26 


H 


header file, purpose of, 5-47—-5—49 
Help menu 

Index selection, 4—50 

location of, 4-49 

On Context entry, 4-62 

On Context selection, 4—50 

On Help selection, 4-50 

On Keys selection, 4—50 


On Version selection, 4—50 
On Window selection, 4—50 
Turtorial selection, 4—50 
Help menus 
context—sensitive, description of, 4-62 
forms of, 4-62 . 
help index entry, 4-62 
help on help entry, 4-62 
help on keys, 4-62 
help on version, 4-63 
Help On Window entry, 4-62 
help tutorial, 4-62 
help windows, 4-63 
HFT Display, aixterm command, characteristics of, 
5-261—5-262 
$HOME/.mwnmrc file, contents of, 2-2 
hooking routines, descriptions of, 5-134 
host, controlling access to, 5-55 
hot spot, example of, 4-15 


ic keyword, 1-27—1-—34 
icon 
getting sizing hints, 5-45 
setting sizing hints, 5-45 
icon box 
description of, 4-9 
illus., 4-9 
icon names 
getting, 5-44 
setting, 5-44 
icon_rules keyword, 1-27—1-34 
icons 
appearance of, 1-4, 1-5 
Desktop directory, defining the behavior of, 
1—7—1—40 
file, defining the behavior of, 1-5—-1—40 
program, defining the behavior of, 1—-5—-1—40 
shapes of, 4-65 
specifying the bit mapped picture file for, using 
picture keyword, 1-32—1-34 
lf Keyword, 1-31—1-34 
images, transferring between client and server, 5-42 
incremental searching, description of, 4-37 
initialization 
actions during, 5-165—5—1 70 
Enhanced X-Windows toolkit, prerequisite 
tasks, 3-21—3-38 
input device model, dual access, use of, 4—11 
input extension events, processing of, 5-143 
input focus, processing events, 5-21 
input focus model 
explicit focus policy, 4-10 
implicit focus policy, 4—11 
use of, 4-10 
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input sources 
adding, 5~186 
removing, 5-186 
InputOnly windows, window fields, defaults for, 5-63 
InoutOutput windows, window fields, defaults for, 
5-63 
insertion cursor, cursor shapes, illus., 4-13 
_ integer resource ID, use of, 5-2 
intrinsics 
description of, 5—-150—5-—155 
geometry management, 5-182 
irreversable actions, user response to, 4-3 


J 


join_style field, values of, 5-79 


K- 
key codes, converting to key symbols, 5-201 
keyboard 
encoding, manipulation of, 5-54—5-—56 
function keys, table of functions, 4-66 
grabbing, subroutines for, 3-13 
interface support, subroutines for, 3-14 
modifier keys, examples of, 4—66 
navigation keys, table of functions, 4-66 
redirecting input to a child, 5-188 
settings, manipulation of, 5~54 
special purpose keys, default keys for, 4-69 
special—purpose keys, table of functions, 4-66 
text, default keys for, 4-68 
ungrabbing, subroutines for, 3-13 
window management, default keys for, 4-68 
keyboard accelerators, description of, 4-42 
keyboard event, manipulating, 5-18 
keyboard events, processing, 5-1 7—-5-32 
keyboards 
conventions, types of, 4—11 
cursors, shapes of, 4-12 
substitutions, table of, 4-12 
keymap, reporting to clients, 5-24—-5-—32 


L 


leave events, compressing, 5-187 

line_style field, values of, 5-79 

line_width field, description of, 5-78 

linking, creating an interface, prerequisite tasks, 
3-28 
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list boxes 
parts of, 4-32 
use of, 4-32 
location cursor 
illus., 4-12 
use of, 4-12 
locked_on_desktop keyword, 1-31—1-34 
Ipfk device, processing events, 5-143—5-—145 
Ipfk input focus events, processing input focus 
events, 5-145—5—170 


managed widgets, mapping, control of, 5-176 
MapNotify events, reporting to clients, 5-26 
MappingNotify events, reporting to ail clients, 
5-26—5-27 
MapReauest events, reporting to clients, 5-28 
me keyword, 1-31—1-34 
memory 
allocating, 5-141 
deallocating, 5-141 
managing, Toolkit memory management 
routines, 5-208 
menu 
defining actions to be carried out, using menu 
keyword, 1-31—1-—34 
selections 
avoiding, 4-43 
methods of, 4-43 
specifying an item on 
using menu_item keyword, 1-32 
using mi keyword, 1-32 
specifying for appearance beside current menu 
using pm keyword, 1-33—-1-34 
using pull_off_menu keyword, 1-33-—1-—34 
menu bar 
location of, 4-22 
topic, selection of, 4-22 
menu bars, illus., 4-23 
menu keyword, 1-31—1-—34 
menu systems, creating, prerequisite tasks, 3-38 
menu_item keyword, 1-32—1-34 
menus 
accessing, methods of, 4—43 
browsing, 4—43 
configuring the appearance of, 2—4 
creating Desktop, 1-10—1-40 
designing, principles of, 4-50—4—-52 
displaying of, 4-42 
Editing Desktop, 1-10—1—40 
mnemonic, example of, 4—41 
selections, purpose of, 4—41 
titles, purpose of, 4—40 


types of, 4-25, 4-38 
message, displaying information in a window, using 
mfyi utility, 1i-39-—1—44 
message area, description of, 4-23 
messages 
building, guidelines for, 4-66 
creating through desktop utilities, procedure of, 
1-—13—1-40 
mfyi utility, 1-39—1-44 
mi keyword, 1-32—1-34 
minicurses, description of, 6-1 
modal widget pop-up, description of, 5-187 
mouse, pointer shapes, illus., 4-15 
mouse actions 
clicking, 4-14 
double-clicking, 4-14 
dragging, 4-14 
pressing, 4-14 
releasing, 4-14 
mouse buttons 
~ left-handed, illus., 4-14 
right-handed, illus., 4-14 
three—button, description of, 4-14 
mouse pointer 
function of, 4-14 
shapes Of, illus., 4-14 


N 


navigation model, description of, 4-15 
notation, using, 5-201 


O 


object classes, description of, 3—1 
object oriented subroutines, categories of, 3—1 
object—action selection model 
non—contiguous selection operation, illus., 4-21 
selection methods, 4-15 
objects, customizing of, 3-3 
option menu 
description of, 4-38 
operation of, 4—39 
Options menu, mnemonic for, 4-48 
output buffer 
flushing, 5-2 
handling, 5-31—5-—32 
OverrideShell widget class, description of, 5-178 


p 


pane, management of, 6-13 


panels, management of, 6-13 
parameter lists 
setting up AlXwindows gadgets, prerequisite 
tasks, 3—23—3-38 
setting up for AlXwindows widgets, prerequisite 
tasks, 3-23—3-38 
pending delete, function of, 4-33 
pi keyword, 1-32—1-34 
picture files 
data, format of, 1-35 
specification of, 1-34 
picture keyword, 1-32—1-34 


pixmaps 
creating, 5-36 
freeing, 5-36 


storage of, 5-2 
pm keyword, 1-33—1-34 
pointer 
grabbing the, 5-53 
shapes of, 4-65 
pointer button, processing events, 5-17 
pointer events, processing, 5—17—5-—18 
pointer grab 
entry events, processing of, 5-20-—5-—32 
exit events, processing of, 5-20—5—21 
pointer motion event, compressing, 5-187—5-191 
pointing devices, use of, 4-13 
points, drawing, 5-40 
poly—graphics primitives, adding, 5-135 
pop-up children, creating, 5-181 
pop-up menu 
advantages of, 4-39 
description of, 4-27, 4-38 
pop—up shell, creating, 5-181 
pop-up widget 
mapping, 5-181—5-—182 
unmapping, 5—182 
pop—up widgets 
managing pop-up children, 5-180 
modal pop—up widget, 5—180 
modeless pop—up widgets, 5—180 
purpose of, 5-180 
spring-loaded pop—up widget, 5-180 
predefined operations, communicating with window 
managers, 5-43 
preprocessor commands, description of, 1-19 
primary windows, description of, 4-5 
private .h file, widget class use, 5—156—-5—158 
process events, description of, 5-15—5—17 


program, building with a compiler command, 5-2 


progress dialog box, purpose of, 4-57 
properties 
changing, 5-51 
obtaining, 5-51 
use of, 5-50 
PropertyNotify events, reporting to clients, 
5-29—5-32 
protocol manager, capabilities of, 3-17 
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protocol manager subroutine, protocol macro, 
differences between, 3-17 
protocol request, sending, 5-139-—5—140 
protocols 
callbacks, types of, 3-18 
description of, 5-248 
error, format of, 5-248 
error codes, description of, 5-252—5-—253 
event, format of, 5-248—5-—249 
management of, 3-16 
managing, subroutines for, 3-14 
reply, format of, 5-248 
request, format of, 5-248 
states of, 3-17 
syntax of, 5-249 
types of, 5—-249—5-252 
public .h file, widget class use, 5-155—5—156 
pull-down menus 
description of, 4-27, 4-38 
operation of, 4-39 
pull_off_menu keyword, 1-33—1-34 
push buttons, parts of, 4-30 


Q 


quark, description of, 5-47—5-—49 
question dialog box 

illus., 4-29 

operation of, 4-57 


R 


radio buttons, parts of, 4-30 
realization 

AlXwindows gadgets, prerequisite tasks, 

3-27—3-28 
AlXwindows widgets, prerequisite tasks, 
3—-27—3-28 

remote connection, setting up, 5-254—5-—259 
ReparentNotify events, reporting to clients, 5-27 
replies 

defining formats, 5-138-—-5—139 
requests 

defining formats, 5-137-—-5—138 
resize, requesting a, 5-183 
resize border, description of, 4—9 
ResizeRequest events, reporting to clients, 

5—28—5-—29 

resource(s) 

application—specific file, requirements of, 5-172 

client specific 

description of, 2-1, 2-4 
syntax of, 2-5 
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component appearance 
description of, 2—1, 2-3—2-6 
syntax for, 2-3—2-6 
converting, 5-194 
creating a list of, 5-192 
defaults, setting dynamically, 3-16 
defaults files, using localized, 3-16 
description file, format of, 2-2 
environment file, requirements of, 5-172 
identifiers, description of, 2-1 
loading, sources of, 5-172 
loading a database for, 5-172 
managing, 5-191 
reading by a client, 5-197 
retrieving from a database, 5—-48—5—49 
setting, method of, 5-191 
specific appearance, description of, 2-1 
specific behavior, description of, 2—1 
storing in a database, 5-48—5—49 
superclass—to—subclass operation, getting as, 
5-192 
values 
data structures location, 3-3 
default files, 3-3 
source code location, 3-3 
writting by a client, 5-197 
resource converter 
invoking, 5-197 
registering a new, 5-196 
writing a new, 5—194——-5-—196 
resource converters, description of, 5-194 
resource database 
entries in, 2-1 
sources of, 2-1 
resource default files, providing, prerequisite tasks 
for, 3-29—3-38 
resource files, formatting, 5-197 
resource manager 
description of, 5—-46—5—49 
include button, 5-46 
naming conventions, 5-46—5-—49 
quarks, use of, 5-47 
storing resources, 5—47 
resource manger, resource name, determining, 
5~-47—5—49 
resource type, mwm functions, availability of, 2-3 
revision, values, storage of, 3-16 
root window, description of, 5—1 
rule files 
actions determined by, 1—1 
characters, special meaning of, 1-19 
comments in, 1-20 
components of, 1~2, 1-17 
control characters in, 1-20 
environment variables, including in, 1-21 
format of, 1-17 
including files in, 1-20 


keywords in, 1-18 

local, 1-3 

location of, 1-18 

mapping strings, defining triggers, 1-36—1-—44 
preprocessor commands, 1-19 

purpose of, 1-17—1—40 

substitutions in, 1-21—-1-23 

trigger_action clauses, use in, 1-37 


S 


sample program 
attributes, using the display constants to 
change the default, 6-18 
using extended curses routines to create 
screen displays, 6-14 
sash, repositioning of, 4—-28 
scale, components of, 4-35 
scanning direction, country of localization, 4-65 
screen 
update routines, use of, 6-4 
updating, description of, 6-4 
visual classes, visual types of, 5-62 
screen text, translation, guidelines for, 4-65 
scroll bars 
components of, 4-35 
description of, 4-24, 4-35 
illus., 4-24 
mouse, operating with a, 4-69 
operating methods, table of, 4-36 
operation of, 4-36 
secondary windows, description of, 4-5 
Select mouse, use of, 4—43 
selection cursor. See location cursor 
SelectionClear events, reporting to a selection 
owner, 5-29 
SelectionNotify events, generating with the 
XSendEvent subroutine, 5-30 
SelectionRequest events, reporting to a selection 
owner, 5—29—5-30 
selections 
defaults, use of, 4—29 
desciption of, 5-52 
separators 
currency, 4-64 
decimal, use of, 4-64 
thousands, use of, 4-64 
server, grabbing the, 5-54 
set subroutines, communicating with window 
managers, 5-43—5—44 
Shell class, AlXwindows Window Manager, 
interfacing with, 3-5 
shell widget 
resizing of, 5-178—5-—180 
characteristics of, 5-178—5—180 


Shell widget class 
description of, 5-178 
hierarchy of, 3-7 
illus., 3-7 
internal, use in, 5-178 
public, use in, 5-178 
ShellClassPart fields, description of, 5-179—5-—180 
ShellPart fields 
defining, 5-180 
defining the default values, 5-180 
shells, predefined class pointers for, 5-179 
single byte, operations, support of, 5-86—5—87 
slider, size of, 4-37 
specific appearance. resource, controlling window 
policies, 2—4 
stack_mode field 
restacking order without sibling, 5-71 
restracking order with sibling, 5-71 
Status, error indication, use as, 5-2 
stepper button, parts of, 4-37 
stipple field, description of, 5-80 
strings, interpretation of, 2-2 
stub 
deriving the correct extension opcode, 5—141 
writing a routine, 5—136—5-—137 
stubs 
description of, 5-134 
writing, 5-136 
superclasses 
calling an unchained operation, 5-163 
chaining operations, 5—-160—5-—161 
inheriting, 5-162—5-—163 
support subroutines, categories of, 3-10 
synchronous calling, use of, 5-140—5-141 
synchronous mode, enabling, 5—-140—5-—141 
system menu. See window menu 
system menu button. See window menu button 


T 


ta keyword, 1-33—1-34 
telephone numbers, format for, 4-65 
terminal, specifications, limitations of, 6—4 
TERMINFO enviroment variable, use of, 6-2 
text, selecting incrementally, 4-70 
text cursors, shapes of, 4-33 
ti keyword, 1-33—1-34 
tile field, description of, 5—80 
time 
formats for, 4-65 
zones for, 4—65 
timeouts . 
adding, 5-186—5-—187 
removing, 5—186—5—187 


Index X—11 


title, assigning to the specified icons 
using ti keyword, 1-33—1-34 
using title keyword, 1-33—1-34 
title area, location of, 4-9 
title keyword, 1-33—1-34 
Toolkit 
initializing, 5-171—5-—173 
multiple display connections, 5-172 
multiple instances, implementation of, 
5-172—5—173 
top-level shells, creating multiple, 5-165—5—170 
top-level windows, adding to AlXwindows interface, 
prerequisite tasks, 3-22 
TopLevelShell widget class, description of, 5-179 
transient property 
getting, 5-45 
setting, 5-45 
TransientShell widget class, VendorShell widget 
class, member of, 5—178 
translation manager 
action table, use of, 5-198 
translation table, use of, 5-198 
translation table 
canonical represenatation of, 5-206 
file, syntax of, 5-201 
modifier errors, 5-202 
modifiers 
syntax of, 5-203 
use of, 5-202 
translation tables 
changing, 5-200 
merging, 5—200 
use of, 5-199 
translator manager, use of, 5-198 
trigger, specifying the results of mouse action on 
icon 
using ta keyword, 1-33—1-34 
using trigger_action keyword, 1-33—1-34 
trigger sets, description of, 1-37 
trigger_action keyword, 1-33—1-—34 
TriggerlD string, purpose of, 1-37 
triggers 
description of, 1-1 
macro definitions, use of, 1-38 
_mapping, format of, 1-36—1-—44 
two byte, operations, support of, 5-86-—5-—87 
type converter, functions of, 5—-194—5~—196 


U- 


UnmapNotify events, reporting to clients, 5-27 
user control, principles of, 4—1 
user interface, guidelines 
generic icons, 1-2 
~ icon design, 1-2 
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user—object interaction 
description of, 4-2 
methods of, 4—2 
/usr/include/Xll/cursorfont.h directory, defining 
cursors in, 5~267—-5—270 


V 


valuators, scale, use of, 4-34 
values 
negative, use of, 4-64 
positive, use of, 4-64 
version, values, storage of, 3-16 
View menu, data, display of, 4—47 
VisibilityNotify events, reporting to clients, 
5~—27—5-28 
visual types, description of, 5-56 


W 


warning dialog box, purpose of, 4-58 
widget, sensitivity state 
checking, 5-189 
setting, 5-189 
widget class, description of, 5-151 
widget classes 
description of, 5-152, 5—155—5-—164 
hierarchy of, 3-1, 3-3 
initializing, 5-161—5-—162 
subclasses, use of, 5-155 
widget instance 
creating, 5-164 
creating a window for, 5-166—5—167 
description of, 5-152 
initializing, 5-165—5—166 
initializing non—widget data, 5—-166—5—170 
widget instances, creating, process of, 5-164 
widget set, description of, 5—150—5-155 
widget tree 
Intrinsics, manipulation by, 5-171—5-173 
up-—traversal of, 5—171 
widgets 
creating 
avoiding 0(n2) process, 5-164 
prerequisite tasks for, 3-26—3-—27 
creating resolution independent, subroutines 
for, 3-13 
defining, 5-151—5-—155 
description of, 3-3 
destroying, 5-168 
down-traversal of, 5-171—5-—173 
exposure, controlling, 5-190 


gadgets, differences between, 3-4 
instantiation of, 3-3 
dialog boxesmanaging the placement of, 5-185 
managing the size of, 5-185 
naming, 5-152—5-—153 
opaque types of, 5-179 
realizing, 5-166 
redisplaying, 5-190 
setting up parameter lists for, 3-23—3-—38 
three files, use of, 5-155 
unrealizing, 5-168 
visibility, controlling, 5-190 
Width, requirements for window, 5—1 
win_gravity field 
NorthWestGravity value, 5-67 
StaticGravity value, 5-67 
UnmapGravity value, 5-67 
window 
configuring, description of, 5-59 
creating, description of, 5-57 
definition of, 4-5, 5-1 
destroying, description of, 5-58 
hierarchy, arrangement in, 5—1 
mapping, description of, 5-58 
obtaining information of, 5-167 
specifying policies of, 2-4 
standard layout, illus., 4—7 
terminal, transferring to, 6-5 
type of, 4-5 
window class 
getting, 5—45 
setting, 5-45 
window control buttons 
functions of, 4-8 
location of, illus., 4-8 
maximize button, 4-9 
minimize button, 4—9 
window crossing event, processing, 5-19 
window management 
functions, specification of, 2-2 
resource sets in, 2-1 
window manager 
application requirements, 5—43—5—45 
defaults, use of, 5—43—5-—45 
getting hints, 5-44 
getting sizing hints, 5-45 
managing messages, subroutines for, 3-14 
managing protocols, subroutines for, 3-14 
messages, application use of, 3-17 
performing predefined property actions, 5—43 
setting hints, 5—44 
setting sizing hints, 5-45 
subroutines, functions of, 5-52 
window menu 
accelerators, table of, 4-8 
operation of, 4—7 
selections, table of, 4—8 
window menu button, operation of, 4—7 


window name 

getting, 5-44 

setting, 5-44 
window panes, description of, 4-24 
window tree, obtaining information on, 5—50 
WMShell widget class, description of, 5-178 
work procedures, adding background, 5-189 


X 


X-Windows Toolkit, data structures, list of, 5-209 
Xlib graphics subroutines, functions of, 5-39 
Xlib library, purpose of, 5—1 
Xlib window information subroutines, functions of, 
5-50 
XmGadget gadget class, hierarchy of, 3-5 
illus., 3-6 
XmList widget list, modifying, subroutines for, 3-12 
XmManager class 
graphics contexts, support of, 3-5 
traversal resources, support of, 3-5 
visual resources, support of, 3-5 
XmManager widget class, hierarchy of, 3-8 
illus., 3-9 
XmText widgets, text manipulation, subroutines for, 
3-14 
Xmtoolkit, 3-38 
XOpenDisplay subroutine, purpose of, 5-12 
XSetStandardProperties subroutine, description of, 
5—43—5-45 
XtAcceptFocusProc data type, example of, 5-238 
XtActionProc procedure pointer, example of, 5-237 
XtAddressMode enumerated type, 5-236 
XtAlmostProc data type, example of, 5-239 
XtArgsFunc data type, example of, 5-239—5-—240 
XtArgsProc data type, description of, 5-216 
XtCallbackProc data type, description of, 5-216 
XtCaseProc data type, example of, 5-238 
XtConverter data type, 5-235 
XtConvertSelectionProc data type, example of, 
5-240—5-241 
XtErrorHandler data type, example of, 5-243 
XtErrorMsgHandler data type, example of, 5-243 
XtEventHandler data type, 5-228 
XtExposeProc data type, 5-228 
XtGeometryHandler data type, 5—230—5-—232 
XtinitProc data type, description of, 5~215 
XtInputCallbackProc data type, example of, 5-244 
XtKeyProc data type, example of, 5-237 
XtLoseSelectionProc data type, description of, 5-241 
XtMainLoop subroutine, adding, 3-27—3-38 
XtOrderProc data type, description of, 5-218 
XtProc data type, description of, 5-244 
XtRealizeProc data type, example of, 5-245—5-~-246 
XtResourceDefaultProc data type, 5—-234 
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XtSelectionCallbackProc data type, example of, 
5-241 

XtSelectionDoneProc data type, example of, 
5-242—5-243 

XtSetValuesFunc data type, example of, 
5-246—5-—247 
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XtStringProc data type, example of, 5-247 
XtTimerCallbackProc procedure, example of, 5-247 
XtWidgetClassProc data type, example of, 5-244 
XtWidgetProc data type, description of, 5-217 
XtWorkProc data type, 5-227 

xy coordinates, defining, 5-50 
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